Viewing docs for an older release. View latest
useNavigate
On this page

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");

to: To

You can also pass a To 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
  • unstable_flushSync: boolean - wraps the initial state update for this navigation in a ReactDOM.flushSync call instead of the default React.startTransition
  • unstable_viewTransition: boolean - enables a View Transition for this navigation by wrapping the final state update in document.startViewTransition()
Docs and examples licensed under MIT