`useNavigation()` hook

useNavigation() gives shared auth components one navigation surface across Next.js, React Router, and TanStack Router. It uses the active adapter when one is available, and it builds the hosted sign-in and sign-up targets from the current deployment settings.

Usage

The following example shows a basic usage of useNavigation().

export default function AuthActions() {  const { navigateToSignIn, navigateToSignUp } = useNavigation();  return (    <div className="flex gap-3">      <button onClick={() => navigateToSignIn()}>Sign in</button>      <button onClick={() => navigateToSignUp()}>Create account</button>    </div>  );}

Return value

The hook returns the following fields and methods.

›

navigate?: (to: string, options?: { replace?: boolean; state?: any }) => void | undefined;

Calls the adapter navigation function when the current framework exposes one. If there is no adapter navigate function, it falls back to assigning `window.location.href`.

›

replace?: boolean | undefined | undefined;

Replaces the current history entry when the adapter supports it.

›

state?: any | undefined;

Framework-specific navigation state passed through to the adapter.

›

navigateToSignIn?: (redirectUri?: string) => void | undefined;

Sends the user to the hosted sign-in page from the deployment UI settings and carries the current redirect target forward.

›

navigateToAccountSelection?: (redirectUri?: string) => void | undefined;

Sends the user to the hosted account-selection surface on the deployment frontend host.

›

navigateToSignUp?: (redirectUri?: string) => void | undefined;

Sends the user to the hosted sign-up page from the deployment UI settings and carries the current redirect target forward.

How it works

The hook is built on top of useDeployment(), so it is only available after <DeploymentProvider /> has resolved the active deployment and adapter.

Hosted redirects reuse an explicit redirectUri when one is passed in. If you do not pass one, the hook first checks for an existing redirect_uri query param on the current page and falls back to window.location.href only when that param is missing.

That redirect precedence is what lets embedded flows hand off to hosted pages without losing the original target page.

In staging, the hosted redirects append __dev_session__ so the development session survives the round trip through the hosted pages.

The generic navigate() helper is intentionally thin. It exists so shared auth components can navigate without caring which router adapter is active.

When to use it

Examples

Send unauthenticated users to sign-in

export default function ProtectedArea() {  const { navigateToSignIn } = useNavigation();  return (    <button onClick={() => navigateToSignIn()}>      Continue to sign in    </button>  );}

Preserve an explicit return URL

export default function CheckoutAuth() {  const { navigateToSignIn } = useNavigation();  return (    <button onClick={() => navigateToSignIn('https://app.example.com/checkout')}>      Sign in to continue    </button>  );}

Open the account-selection page

export default function MoreAccounts() {  const { navigateToAccountSelection } = useNavigation();  return (    <button onClick={() => navigateToAccountSelection()}>      Use another account    </button>  );}

useNavigation() hook