Docs

useNavigate

The useNavigate hook returns a function that lets you navigate programmatically in the browser in response to user interactions or effects.

import { useNavigate } from "@remix-run/react";

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

It's often better to use redirect in actions and loaders than this hook, but it still has use cases.

#Arguments

#to: string

The most basic usage takes an href string:

navigate("/some/path");

Paths can be relative:

navigate("..");
navigate("../other/path");
Please see the Splat Paths section on the useResolvedPath docs for a note on the behavior of the future.v3_relativeSplatPath future flag for relative useNavigate() behavior within splat routes

#to: Partial<Path>

You can also pass a Partial<Path> value:

navigate({
  pathname: "/some/path",
  search: "?query=string",
  hash: "#hash",
});

#to: Number

Passing a number will tell the browser to go back or forward in the history stack:

navigate(-1); // go back
navigate(1); // go forward
navigate(-2); // go back two

Note that this may send you out of your application since the history stack of the browser isn't scoped to just your application.

#options

The second argument is an options object:

navigate(".", {
  replace: true,
  relative: "path",
  state: { some: "state" },
});
  • replace: boolean - replace the current entry in the history stack instead of pushing a new one
  • relative: "route" | "path" - defines the relative path behavior for the link
    • "route" will use the route hierarchy so ".." will remove all URL segments of the current route pattern while "path" will use the URL path so ".." will remove one URL segment
  • state: any - adds persistent client side routing state to the next location
  • preventScrollReset: boolean - if you are using <ScrollRestoration>, prevent the scroll position from being reset to the top of the window when navigating
  • flushSync: boolean - wraps the initial state update for this navigation in a ReactDOM.flushSync call instead of the default React.startTransition
  • viewTransition: boolean - enables a View Transition for this navigation by wrapping the final state update in document.startViewTransition()
    • If you need to apply specific styles for this view transition, you will also need to leverage the useViewTransitionState()