A navigate function for programmatic navigation
import { useNavigate } from "react-router";
function SomeComponent() {
let navigate = useNavigate();
return (
<button onClick={() => navigate(-1)}>
Go Back
</button>
);
}
navigate("/some/route");
navigate("/some/route?search=param");
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).
// 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`](https://developer.mozilla.org/en-US/docs/Web/API/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.
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 });
[MODES: 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.
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:
typescript-eslint, you may see errors from
@typescript-eslint/no-floating-promisesReact.use(navigate()) will show a false-positive
Argument of type 'void | Promise<void>' is not assignable to parameter of type 'Usable<void>' errorThe 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>;
}
}
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/loaderfunctions than this hook.The returned function signature is
navigate(to, options?)/navigate(delta)where:tocan be a string path, a To object, or a number (delta)optionscontains options for modifying the navigationrelative:"route"or"path"to control relative routing logicreplace: Replace the current entry in theHistorystackstate: Optionalhistory.stateto include with the new LocationflushSync: Wrap the DOM updates inReactDom.flushSyncpreventScrollReset: Do not scroll back to the top of the page after navigationviewTransition: Enabledocument.startViewTransitionfor this navigation