Skip to main content

​
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
Numeric Navigation:
​
delta
number
required
Number of entries to go back (negative) or forward (positive) in the history stack.

​
Usage

import { useNavigate } from "react-router";

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

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

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"
}

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>;
  }
}
  • <Link> - Declarative navigation component
  • <Navigate> - Declarative navigation component for redirects
  • redirect - Server-side redirect utility
  • useLocation - Access current location

Build docs developers (and LLMs) love

Get started for freeTalk to us