Skip to content
Twilight React Playground
ثيم رائدaren

useNavigate

hookBeginnerbrowserlive demo

Returns a navigate(path) function that moves to another store page from code, without reloading the whole page.

import { useNavigate, NavigateFn, NavigateOptions } from '@salla.sa/twilight-theme-engine/providers';

In plain words

Links are for things people click. When your code decides where to go, for example after a form is sent, call the function useNavigate() gives you: navigate('/cart').

Write the path without the language. On a multilingual store the engine adds the current one, so /cart becomes /ar/cart. Pass { replace: true } when the browser's Back button should skip the page you are leaving.

Signature

function useNavigate(): NavigateFn

type NavigateFn = (to: string, opts?: NavigateOptions) => void;
type NavigateOptions = { replace?: boolean };

Try it live

useNavigate() returns a function that moves to another page without reloading it. Paths carry no locale: it is added for you.Try this: pick /cart, turn replace on, go, then press Back: you skip past this page.
Storefront canvas · ar · RTL
This leaves the page. The browser’s Back button brings you back here.
Controls
replaceReplace the current history entry instead of adding one.
What a theme writes
import { useNavigate } from '@salla.sa/twilight-theme-engine/providers';

export function GoButton() {
  const navigate = useNavigate();
  return (
    <button type="button" onClick={() => navigate('/playground/reference/core')}>
      Continue
    </button>
  );
}

Example

app/components/ContinueShopping.tsx
import { useNavigate } from '@salla.sa/twilight-theme-engine/providers';

export function ContinueShopping() {
  const navigate = useNavigate();
  return (
    <button type="button" className="btn btn--primary" onClick={() => navigate('/offers')}>
      Continue shopping
    </button>
  );
}

How it behaves

  • Under TwilightProvider the function comes from the TanStack setup (src/tanstack/navigation.tsx): it calls TanStack Router's navigate({ to, replace }), after localizeDestination prefixes the current locale route param to a path that starts with / and has no locale yet.

  • On localhost and the preview host the router also adds the store segment, so always pass application paths.

  • A query string is fine: the engine's own product listing navigates to useLocation().pathname followed by ? and its search params.

  • The function changes identity only when the locale does, so it is safe in effect dependency lists.

Gotchas

  • Never build to from the path in window.location: on localhost and the preview host the address bar carries the store segment and the router adds it again (/dev-…/dev-…/cart). Use useLocation().pathname.

  • Outside a NavigationProvider it does not throw. It returns a fallback that assigns the path to window.location (or calls location.replace): a full page load, with no locale added. That is what code inside TwilightProvider's skeleton or under client={false} gets.

Related

useLocation

Reads the current address as the router sees it (path, parsed query, raw query, hash), in the server render and in the browser.

NavigationProvider

Supplies the function useNavigate() returns to everything below it; TwilightProvider mounts one for TanStack Router, and tests can mount their own.

notFound, redirect, unauthorized

Throw helpers for route loaders: stop and show the not-found page, send the visitor to another address, or refuse a guest.

Source and docs