useRouter

Returns a static object used for routing. This hook will never update, and is only used for imperatively controlling the router.

It takes no arguments and returns object of type:

type Router = {
  /** Go back in the history. */
  back: () => void
  /** If there's history that supports invoking the `back` function. */
  canGoBack: () => boolean
  /** Navigate to the provided href using a push operation if possible. */
  push: (href: Href, options?: LinkToOptions) => void
  /** Navigate to the provided href. */
  navigate: (href: Href, options?: LinkToOptions) => void
  /** Navigate to route without appending to the history. */
  replace: (href: Href, options?: LinkToOptions) => void
  /** Navigate to the provided href using a push operation if possible. */
  dismiss: (count?: number) => void
  /** Navigate to first screen within the lowest stack. */
  dismissAll: () => void
  /** If there's history that supports invoking the `dismiss` and `dismissAll` function. */
  canDismiss: () => boolean
  /** Update the current route query params. */
  setParams: <T = ''>(
    params?: T extends '' ? Record<string, string | undefined | null> : InputRouteParams<T>
  ) => void
  /** Subscribe to state updates from the router */
  subscribe: (listener: RootStateListener) => () => void
  /** Subscribe to loading state updates */
  onLoadState: (listener: LoadingStateListener) => () => void
}

type LinkToOptions = {
  /** Disable scroll restoration on navigation */
  scroll?: boolean
  /** Display a different URL in the browser (web only) */
  mask?: {
    href: Href
  }
}

Route Masking

You can display a different URL in the browser address bar while navigating to a specific route. This is useful for modals, side panels, or keeping URLs clean:

const router = useRouter()

// Navigate to /photos/5/modal but show /photos/5 in the URL bar
router.push('/photos/5/modal', {
  mask: { href: '/photos/5' }
})

When users click back/forward, the actual route state is restored from history. This feature is web-only.

Introduction

Edit this page on GitHub.

Github

Discord

Blog