Hooks

Hooks API

Type-safe hooks for accessing router state and navigation.

useRouter

Access the current TanStack Router instance from React context.

import { useRouter } from '@tanstack/react-router'

function MyComponent() {
  const router = useRouter()
  
  const handleInvalidate = () => {
    router.invalidate()
  }
  
  return <button onClick={handleInvalidate}>Refresh Data</button>
}

Options

warn · boolean · default: "true"

Log a warning if no router context is found.

Returns

router · Router

The registered router instance with methods like navigate, invalidate, preloadRoute, etc.

useNavigate

Imperative navigation hook.

import { useNavigate } from '@tanstack/react-router'

function MyComponent() {
  const navigate = useNavigate()
  
  const goToPosts = () => {
    navigate({ to: '/posts', search: { page: 1 } })
  }
  
  return <button onClick={goToPosts}>View Posts</button>
}

Options

from · string

Optional route base used to resolve relative to paths.

const navigate = useNavigate({ from: '/posts' })
navigate({ to: './create' }) // navigates to /posts/create

Returns

navigate · Function

A stable function that accepts NavigateOptions:

• to - Destination route path
• params - Path parameters
• search - Search parameters (object or updater function)
• hash - Hash fragment
• state - History state
• replace - Replace history entry instead of push
• resetScroll - Reset scroll position
• viewTransition - Use View Transitions API

useParams

Access the current route’s path parameters with type-safety.

import { useParams } from '@tanstack/react-router'

function PostComponent() {
  const { postId } = useParams({ from: '/posts/$postId' })
  return <div>Post ID: {postId}</div>
}

Options

from · string

The route path to get params from. Enables strict typing.

const params = useParams({ from: '/posts/$postId' })
// params is typed as { postId: string }

strict · boolean · default: "true"

If true, only the route’s own params are returned. If false, all params from parent routes are included.

select · (params) => any

Project the params object to a derived value for memoized renders.

const postId = useParams({
  from: '/posts/$postId',
  select: (params) => params.postId,
})

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

params · object

The params object (or selected value) for the matched route.

useSearch

Read and select the current route’s search parameters with type-safety.

import { useSearch } from '@tanstack/react-router'

function PostsComponent() {
  const { page, filter } = useSearch({ from: '/posts' })
  return <div>Page {page}</div>
}

Options

from · string

The route path to get search params from. Enables strict typing.

const search = useSearch({ from: '/posts' })
// search is typed based on the route's validateSearch

strict · boolean · default: "true"

Control which route’s search is read and how strictly it’s typed.

select · (search) => any

Map the search object to a derived value for render optimization.

const page = useSearch({
  from: '/posts',
  select: (search) => search.page,
})

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

search · object

The search object (or selected value) for the matched route.

useLoaderData

Read and select the current route’s loader data with type-safety.

import { useLoaderData } from '@tanstack/react-router'

function PostComponent() {
  const { post } = useLoaderData({ from: '/posts/$postId' })
  return <h1>{post.title}</h1>
}

Options

from · string

The route path to get loader data from. Enables strict typing.

const data = useLoaderData({ from: '/posts/$postId' })
// data is typed based on the route's loader return type

strict · boolean · default: "true"

Choose which route’s data to read and strictness.

select · (data) => any

Map the loader data to a derived value.

const title = useLoaderData({
  from: '/posts/$postId',
  select: (data) => data.post.title,
})

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

data · any

The loader data (or selected value) for the matched route.

useLoaderDeps

Access the current route’s loader dependencies.

import { useLoaderDeps } from '@tanstack/react-router'

function PostsComponent() {
  const { page } = useLoaderDeps({ from: '/posts' })
  return <div>Current page: {page}</div>
}

Options

from · string

The route path to get loader deps from.

strict · boolean · default: "true"

Control strictness of typing.

select · (deps) => any

Map the deps to a derived value.

Returns

deps · any

The loader dependencies for the matched route.

useMatch

Get the current route match data.

import { useMatch } from '@tanstack/react-router'

function MyComponent() {
  const match = useMatch({ from: '/posts/$postId' })
  
  return (
    <div>
      <div>Route ID: {match.routeId}</div>
      <div>Status: {match.status}</div>
    </div>
  )
}

Options

from · string

The route path to match against.

strict · boolean · default: "true"

Whether to enforce strict typing.

select · (match) => any

Select a derived value from the match.

const status = useMatch({
  from: '/posts/$postId',
  select: (match) => match.status,
})

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

match · RouteMatch

The route match object containing:

• id - Unique match identifier
• routeId - The route’s ID
• pathname - The matched pathname
• params - Path parameters
• search - Search parameters
• loaderData - Data from the loader
• status - Match status (‘pending’ | ‘success’ | ‘error’)
• And more…

useLocation

Get the current location object.

import { useLocation } from '@tanstack/react-router'

function MyComponent() {
  const location = useLocation()
  
  return (
    <div>
      <div>Pathname: {location.pathname}</div>
      <div>Search: {JSON.stringify(location.search)}</div>
      <div>Hash: {location.hash}</div>
    </div>
  )
}

Returns

location · ParsedLocation

The current location object with:

• href - The full URL path
• pathname - The pathname
• search - Parsed search parameters
• searchStr - Raw search string
• hash - The hash fragment
• state - History state

useRouterState

Subscribe to router state with optional selection.

import { useRouterState } from '@tanstack/react-router'

function MyComponent() {
  const isLoading = useRouterState({
    select: (state) => state.isLoading,
  })
  
  return isLoading ? <div>Loading...</div> : null
}

Options

select · (state) => any

Select a derived value from the router state.

const matches = useRouterState({
  select: (state) => state.matches,
})

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

state · RouterState | any

The router state (or selected value) containing:

• status - Router status (‘pending’ | ‘idle’)
• isLoading - Whether the router is loading
• isTransitioning - Whether a navigation is in progress
• matches - Current route matches
• location - Current location
• resolvedLocation - Resolved location after redirects

useRouteContext

Access the current route’s context.

import { useRouteContext } from '@tanstack/react-router'

function MyComponent() {
  const context = useRouteContext({ from: '/posts/$postId' })
  
  return <div>User: {context.user.name}</div>
}

Options

from · string

The route path to get context from.

strict · boolean · default: "true"

Whether to enforce strict typing.

select · (context) => any

Select a derived value from the context.

const user = useRouteContext({
  from: '/posts',
  select: (context) => context.user,
})

Returns

context · any

The route context object.

useBlocker

Block navigation based on a condition.

import { useBlocker } from '@tanstack/react-router'

function FormComponent() {
  const [isDirty, setIsDirty] = useState(false)
  
  useBlocker({
    condition: isDirty,
    blockerFn: () => window.confirm('You have unsaved changes. Leave anyway?'),
  })
  
  return <form>{/* form fields */}</form>
}

Options

condition · boolean · required

Whether to block navigation.

blockerFn · () => boolean | Promise<boolean> · required

A function that returns true to allow navigation or false to block it.

Returns

Void. The hook sets up the blocker internally.

useMatches

Get all current route matches.

import { useMatches } from '@tanstack/react-router'

function Breadcrumbs() {
  const matches = useMatches()
  
  return (
    <nav>
      {matches.map((match) => (
        <span key={match.id}>{match.route.path}</span>
      ))}
    </nav>
  )
}

Options

select · (matches) => any

Select a derived value from the matches array.

structuralSharing · boolean

Enable structural sharing for stable references.

Returns

matches · RouteMatch[]

Array of all current route matches from root to leaf.

useCanGoBack

Check if the router can go back in history.

import { useCanGoBack } from '@tanstack/react-router'

function BackButton() {
  const canGoBack = useCanGoBack()
  const navigate = useNavigate()
  
  return (
    <button
      onClick={() => navigate({ to: '..' })}
      disabled={!canGoBack}
    >
      Back
    </button>
  )
}

Returns

canGoBack · boolean

Whether the router can navigate back in history.