Navigation

Navigate between routes using links and programmatic navigation

TanStack Router provides multiple ways to navigate between routes: declarative links, programmatic navigation, and redirect functions.

Link Component

The Link component provides type-safe navigation with automatic preloading:

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

function Navigation() {
  return (
    <Link to="/posts/$postId" params={{ postId: '123' }}>
      View Post
    </Link>
  )
}

Link Props

to · string · required

The destination path. Can be absolute or relative:

<Link to="/about">About</Link>
<Link to="./details">Details</Link>
<Link to="../.." >Back Two Levels</Link>

params · object

Path parameters for the destination route:

<Link to="/posts/$postId" params={{ postId: '123' }}>
  View Post
</Link>

search · object | function

Search parameters for the URL. Can be an object or updater function:

{/* Set search params */}
<Link to="/posts" search={{ page: 1, filter: 'recent' }}>
  Posts
</Link>

{/* Update existing search params */}
<Link to="." search={(prev) => ({ ...prev, page: prev.page + 1 })}>
  Next Page
</Link>

hash · string

URL hash (without the #):

<Link to="/docs" hash="introduction">
  Jump to Introduction
</Link>

state · object

History state (not visible in URL):

<Link to="/posts" state={{ from: 'homepage' }}>
  Posts
</Link>

from · string

The source route for type-safe relative navigation:

<Link from="/posts/$postId" to="./edit">
  Edit Post
</Link>

Styling Active Links

Use activeProps and inactiveProps to style links based on active state:

<Link
  to="/posts"
  activeProps={{
    className: 'font-bold text-blue-600',
    'aria-current': 'page',
  }}
  inactiveProps={{
    className: 'text-gray-600',
  }}
>
  Posts
</Link>

Or use activeOptions to customize when a link is considered active:

<Link
  to="/posts"
  activeOptions={{
    exact: true, // Only active on exact match
    includeHash: false, // Ignore hash when determining active
    includeSearch: true, // Include search params in comparison
  }}
>
  Posts
</Link>

Preloading

preload · false | 'intent' | 'viewport' | 'render'

Control when to preload the destination route:

• false - No preloading
• 'intent' - Preload on hover/touch (default)
• 'viewport' - Preload when link enters viewport
• 'render' - Preload immediately when rendered

<Link to="/posts/$postId" params={{ postId: '123' }} preload="viewport">
  View Post
</Link>

preloadDelay · number · default: "50"

Delay in milliseconds before preloading on hover.

Replace Navigation

replace · boolean · default: "false"

Replace the current history entry instead of pushing a new one:

<Link to="/posts" replace>
  View Posts
</Link>

Disabled Links

<Link to="/posts" disabled={!hasPermission}>
  Posts
</Link>

Disabled links render as spans and don’t navigate.

Programmatic Navigation

Use the useNavigate hook for programmatic navigation:

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

function MyComponent() {
  const navigate = useNavigate()
  
  const handleClick = async () => {
    await navigate({
      to: '/posts/$postId',
      params: { postId: '123' },
      search: { comment: 'abc' },
    })
    console.log('Navigation complete')
  }
  
  return <button onClick={handleClick}>View Post</button>
}

Navigate Options

The navigate function accepts the same options as Link:

await navigate({
  to: '/posts',
  search: { page: 1 },
  hash: 'comments',
  replace: true,
  state: { from: 'search' },
})

Navigate from Loaders

You can also navigate from route loaders:

const postRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts/$postId',
  beforeLoad: async ({ params, navigate }) => {
    const post = await fetchPost(params.postId)
    
    if (post.isDraft) {
      await navigate({ to: '/drafts/$postId', params })
    }
    
    return { post }
  },
})

The navigate function in loaders is deprecated. Use redirect() instead (see below).

Redirects

Use the redirect function to redirect during data loading:

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

const protectedRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/dashboard',
  beforeLoad: ({ context, location }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({
        to: '/login',
        search: { redirect: location.href },
      })
    }
  },
})

Route-Specific Redirects

Each route has a redirect method for relative redirects:

const postRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts/$postId',
  beforeLoad: ({ params }) => {
    if (!isValidPostId(params.postId)) {
      // Relative redirect
      throw postRoute.redirect({ to: './list' })
    }
  },
})

Redirect Options

from · string

Source route for relative redirects (set automatically with route.redirect()).

to · string · required

Destination path.

params · object

Path parameters for the destination.

search · object

Search parameters for the destination.

hash · string

URL hash for the destination.

replace · boolean · default: "false"

Replace current history entry.

code · number

HTTP status code for server-side redirects.

History Navigation

Navigate through browser history:

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

function BackButton() {
  const router = useRouter()
  
  return (
    <button onClick={() => router.history.back()}>
      Go Back
    </button>
  )
}

History Methods

const router = useRouter()

// Navigate back
router.history.back()

// Navigate forward
router.history.forward()

// Navigate to specific position
router.history.go(-2) // Go back 2 pages
router.history.go(1)  // Go forward 1 page

Relative Navigation

TanStack Router supports several relative navigation patterns:

Current Route

// Stay on same route, update search params
<Link to="." search={{ page: 2 }}>Next Page</Link>

// Navigate to child
<Link to="./details">View Details</Link>

Parent Routes

// Navigate to parent
<Link to="..">Back</Link>

// Navigate to grandparent
<Link to="../..">Back Two Levels</Link>

// Navigate to sibling
<Link to="../other">Other Page</Link>

Type-Safe Relative Navigation

Specify the from route for full type safety:

function PostComponent() {
  return (
    <Link from="/posts/$postId" to="../..">
      Back to Home
    </Link>
  )
}

Router API

Access the router instance for advanced navigation:

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

function Component() {
  const router = useRouter()
  
  // Get current location
  const location = router.state.location
  
  // Build a location
  const nextLocation = router.buildLocation({
    to: '/posts',
    search: { page: 2 },
  })
  
  // Navigate
  await router.navigate(nextLocation)
  
  // Preload a route
  await router.preloadRoute({
    to: '/posts/$postId',
    params: { postId: '123' },
  })
}

View Transitions

Enable smooth transitions between routes:

// Enable globally
const router = createRouter({
  routeTree,
  defaultViewTransition: true,
})

// Or per-navigation
await navigate({
  to: '/posts',
  viewTransition: true,
})

Configure transition types:

const router = createRouter({
  routeTree,
  defaultViewTransition: {
    types: ['slide', 'fade'],
  },
})

Scroll Behavior

Hash Scrolling

Automatically scroll to elements with matching IDs:

<Link to="/docs" hash="getting-started">
  Getting Started
</Link>

Customize scroll behavior:

const router = createRouter({
  routeTree,
  defaultHashScrollIntoView: {
    behavior: 'smooth',
    block: 'start',
  },
})

Scroll Restoration

Enable automatic scroll position restoration:

const router = createRouter({
  routeTree,
  scrollRestoration: true,
  scrollRestorationBehavior: 'smooth',
})

Next Steps

Search Params

Manage URL search parameters

Path Params

Extract and validate path parameters

Type Safety

Configure end-to-end type safety

Loaders

Load data before rendering routes