useNavigate

useNavigate

Returns a function that lets you navigate programmatically in the browser in response to user interactions or effects.

It’s often better to use redirect in action/loader functions than this hook.

Signature

function useNavigate(): NavigateFunction

interface NavigateFunction {
  (to: To, options?: NavigateOptions): void | Promise<void>;
  (delta: number): void | Promise<void>;
}

Parameters

None.

Returns

navigate · NavigateFunction

A function for programmatic navigation with two overload signatures:

String/Object Navigation:

to · string | To · required

The destination to navigate to. Can be a string path or an object with pathname, search, hash, and state properties.

options · NavigateOptions

Show properties

replace · boolean

Replace the current entry in the history stack instead of pushing a new one.

state · any

Optional state to include with the new location. Access with useLocation().state.

relative · 'route' | 'path'

Controls relative routing logic. Defaults to "route".

preventScrollReset · boolean

Prevent <ScrollRestoration> from resetting scroll position (Framework/Data modes only).

flushSync · boolean

Wrap DOM updates in ReactDOM.flushSync (Framework/Data modes only).

viewTransition · boolean

Enable document.startViewTransition for this navigation (Framework/Data modes only).

Numeric Navigation:

delta · number · required

Number of entries to go back (negative) or forward (positive) in the history stack.

Usage

Navigate to a path

import { useNavigate } from "react-router";

function SomeComponent() {
  const navigate = useNavigate();
  
  return (
    <button onClick={() => navigate("/dashboard")}>
      Go to Dashboard
    </button>
  );
}

Navigate with search params

navigate("/search?q=react+router");

Navigate with a To object

navigate({
  pathname: "/projects",
  search: "?sort=date",
  hash: "#results",
  state: { from: "home" },
});

Access the state on the next page:

function Projects() {
  const location = useLocation();
  console.log(location.state?.from); // "home"
}

Navigate back/forward

function BackButton() {
  const navigate = useNavigate();
  
  return (
    <button onClick={() => navigate(-1)}>
      Go Back
    </button>
  );
}

Be cautious with navigate(number). There may not be a history entry to go back/forward to, or it might navigate to a different domain.

Replace current entry

// Replace the current history entry instead of pushing
navigate("/login", { replace: true });

This is useful for redirects where you don’t want the user to go back to the previous page.

Prevent scroll reset

// Keep scroll position (e.g., for tab navigation)
navigate("?tab=settings", { preventScrollReset: true });

Call in useEffect

Call navigate() in a React.useEffect(), not during component render.

function Component() {
  const navigate = useNavigate();
  const { user } = useLoaderData();
  
  useEffect(() => {
    if (!user) {
      navigate("/login");
    }
  }, [user, navigate]);
  
  return <div>...</div>;
}

Type Safety

Return Type Augmentation

The return type is void | Promise<void> because the implementation differs between Declarative mode and Data/Framework modes. To avoid TypeScript errors, augment the type based on your router:

Declarative Mode (<BrowserRouter>):

declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): void;
    (delta: number): void;
  }
}

Data/Framework Mode (<RouterProvider>):

declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): Promise<void>;
    (delta: number): Promise<void>;
  }
}

Related

• <Link> - Declarative navigation component
• <Navigate> - Declarative navigation component for redirects
• redirect - Server-side redirect utility
• useLocation - Access current location