useNavigate

Framework Data Declarative

Summary

Reference Documentation ↗

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.

The returned function signature is navigate(to, options?)/navigate(delta) where:

• to can be a string path, a To object, or a number (delta)
• options contains options for modifying the navigation
  • These options work in all modes (Framework, Data, and Declarative):
    • relative: "route" or "path" to control relative routing logic
    • replace: Replace the current entry in the History stack
    • state: Optional history.state to include with the new Location
  • These options only work in Framework and Data modes:
    • flushSync: Wrap the DOM updates in ReactDom.flushSync
    • preventScrollReset: Do not scroll back to the top of the page after navigation
    • viewTransition: Deprecated. Use React's <ViewTransition> component instead. See the migration guide.

import { useNavigate } from "react-router";

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

Signature

function useNavigate(): NavigateFunction

Returns

A navigate function for programmatic navigation

Examples

Navigate to another path

navigate("/some/route");
navigate("/some/route?search=param");

Navigate with a To object

All properties are optional.

navigate(
  {
    pathname: "/some/route",
    search: "?search=param",
    hash: "#hash",
  },
  {
    state: { some: "state" },
  },
);

If you use state, that will be available on the Location object on the next page. Access it with useLocation().state (see useLocation).

Navigate back or forward in the history stack

// back
// often used to close modals
navigate(-1);

// forward
// often used in a multistep wizard workflows
navigate(1);

Be cautious with navigate(number). If your application can load up to a route that has a button that tries to navigate forward/back, there may not be a History entry to go back or forward to, or it can go somewhere you don't expect (like a different domain).

Only use this if you're sure they will have an entry in the History stack to navigate to.

Replace the current entry in the history stack

This will remove the current entry in the History stack, replacing it with a new one, similar to a server side redirect.

navigate("/some/route", { replace: true });

Prevent Scroll Reset

Framework Data

To prevent <ScrollRestoration> from resetting the scroll position, use the preventScrollReset option.

navigate("?some-tab=1", { preventScrollReset: true });

For example, if you have a tab interface connected to search params in the middle of a page, and you don't want it to scroll to the top when a tab is clicked.

Return Type Augmentation

Internally, useNavigate uses a separate implementation when you are in Declarative mode versus Data/Framework mode - the primary difference being that the latter is able to return a stable reference that does not change identity across navigations. The implementation in Data/Framework mode also returns a Promise that resolves when the navigation is completed. This means the return type of useNavigate is void | Promise<void>. This is accurate, but can lead to some red squigglies based on the union in the return value:

• If you're using typescript-eslint, you may see errors from @typescript-eslint/no-floating-promises
• In Framework/Data mode, React.use(navigate()) will show a false-positive Argument of type 'void | Promise<void>' is not assignable to parameter of type 'Usable<void>' error

The easiest way to work around these issues is to augment the type based on the router you're using:

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

// If using <RouterProvider> or Framework mode
declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): Promise<void>;
    (delta: number): Promise<void>;
  }
}