> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/remix-run/react-router/llms.txt
> Use this file to discover all available pages before exploring further.

# useNavigate

# useNavigate

Returns a function that lets you navigate programmatically in the browser in response to user interactions or effects.

<Note>
  It's often better to use `redirect` in `action`/`loader` functions than this hook.
</Note>

## Signature

```tsx theme={null}
function useNavigate(): NavigateFunction

interface NavigateFunction {
  (to: To, options?: NavigateOptions): void | Promise<void>;
  (delta: number): void | Promise<void>;
}
```

## Parameters

None.

## Returns

<ResponseField name="navigate" type="NavigateFunction">
  A function for programmatic navigation with two overload signatures:

  **String/Object Navigation:**

  <ParamField path="to" type="string | To" required>
    The destination to navigate to. Can be a string path or an object with `pathname`, `search`, `hash`, and `state` properties.
  </ParamField>

  <ParamField path="options" type="NavigateOptions">
    <Expandable title="properties">
      <ResponseField name="replace" type="boolean">
        Replace the current entry in the history stack instead of pushing a new one.
      </ResponseField>

      <ResponseField name="state" type="any">
        Optional state to include with the new location. Access with `useLocation().state`.
      </ResponseField>

      <ResponseField name="relative" type="'route' | 'path'">
        Controls relative routing logic. Defaults to `"route"`.
      </ResponseField>

      <ResponseField name="preventScrollReset" type="boolean">
        Prevent `<ScrollRestoration>` from resetting scroll position (Framework/Data modes only).
      </ResponseField>

      <ResponseField name="flushSync" type="boolean">
        Wrap DOM updates in `ReactDOM.flushSync` (Framework/Data modes only).
      </ResponseField>

      <ResponseField name="viewTransition" type="boolean">
        Enable `document.startViewTransition` for this navigation (Framework/Data modes only).
      </ResponseField>
    </Expandable>
  </ParamField>

  **Numeric Navigation:**

  <ParamField path="delta" type="number" required>
    Number of entries to go back (negative) or forward (positive) in the history stack.
  </ParamField>
</ResponseField>

## Usage

### Navigate to a path

```tsx theme={null}
import { useNavigate } from "react-router";

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

### Navigate with search params

```tsx theme={null}
navigate("/search?q=react+router");
```

### Navigate with a To object

```tsx theme={null}
navigate({
  pathname: "/projects",
  search: "?sort=date",
  hash: "#results",
  state: { from: "home" },
});
```

Access the state on the next page:

```tsx theme={null}
function Projects() {
  const location = useLocation();
  console.log(location.state?.from); // "home"
}
```

### Navigate back/forward

```tsx theme={null}
function BackButton() {
  const navigate = useNavigate();
  
  return (
    <button onClick={() => navigate(-1)}>
      Go Back
    </button>
  );
}
```

<Warning>
  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.
</Warning>

### Replace current entry

```tsx theme={null}
// 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

```tsx theme={null}
// Keep scroll position (e.g., for tab navigation)
navigate("?tab=settings", { preventScrollReset: true });
```

### Call in useEffect

<Warning>
  Call `navigate()` in a `React.useEffect()`, not during component render.
</Warning>

```tsx theme={null}
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>`):**

```ts theme={null}
declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): void;
    (delta: number): void;
  }
}
```

**Data/Framework Mode (`<RouterProvider>`):**

```ts theme={null}
declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): Promise<void>;
    (delta: number): Promise<void>;
  }
}
```

## Related

* [`<Link>`](/api/components/link) - Declarative navigation component
* [`<Navigate>`](/api/components/navigate) - Declarative navigation component for redirects
* [`redirect`](/api/utils/redirect) - Server-side redirect utility
* [`useLocation`](/api/hooks/use-location) - Access current location