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.

useNavigationContainerRef

Returns a ref to the NavigationContainer component. This allows direct access to the React Navigation container.

import { useNavigationContainerRef } from 'one'

function Component() {
  const navigationContainerRef = useNavigationContainerRef()

  // The ref.current is null until the NavigationContainer mounts
  if (navigationContainerRef.current) {
    // Access React Navigation API
    const state = navigationContainerRef.current.getRootState()
  }
}

This is primarily useful for advanced React Navigation integration. Most use cases should use useRouter() instead.

useUnstableGlobalHref

Returns the current global pathname with query parameters attached. This is an internal API and may change.

import { useUnstableGlobalHref } from 'one'

function Component() {
  const href = useUnstableGlobalHref()
  // e.g., '/docs/routing?tab=settings'
}

This hook is marked unstable and subject to change. Use usePathname() and useSearchParams() for stable alternatives.

PreviousPresentations

useParams

Edit this page on GitHub.

useRouter

Route Masking

Related Hooks

useNavigationContainerRef

useUnstableGlobalHref