Skip to main content

​
Link

Type-safe navigation components and utilities for creating links in TanStack Router.

​
LinkOptions

Configuration options for link navigation.
​
to
string
required
The destination path. Can be absolute or relative.
to="/posts"              // Absolute
to="./details"           // Relative to current route
to="../"                 // Parent route
​
from
string
The source path for type inference. Enables better autocomplete.
from="/posts"
to="./$postId"
​
params
Record<string, any>
Path parameters for the destination route.
to="/posts/$postId"
params={{ postId: '123' }}
​
search
Record<string, any> | (prev) => Record<string, any>
Search parameters for the destination route. Can be an object or updater function.
search={{ page: 1, filter: 'recent' }}
search={(prev) => ({ ...prev, page: prev.page + 1 })}
​
hash
string | (prev) => string
URL hash for the destination.
hash="#comments"
hash={(prev) => prev === '#top' ? '#bottom' : '#top'}
​
state
any | (prev) => any
History state for the navigation.
state={{ from: 'homepage' }}
​
replace
boolean
Replace current history entry instead of pushing a new one.Default: false
​
resetScroll
boolean
Reset scroll position when navigating.Default: true
​
startTransition
boolean
Wrap navigation in React.startTransition.Default: false
​
viewTransition
boolean | ViewTransitionOptions
Use View Transition API for navigation animation.
viewTransition={true}
viewTransition={{ name: 'slide' }}
​
preload
false | 'intent' | 'viewport' | 'render'
When to preload the destination route:
  • false - Don’t preload
  • 'intent' - Preload on hover/focus
  • 'viewport' - Preload when in viewport
  • 'render' - Preload immediately
​
preloadDelay
number
Delay in milliseconds before preloading.Default: 50
​
disabled
boolean
Disable the link navigation.Default: false
​
target
string
Standard anchor target attribute (_blank, _self, etc.).
​
activeOptions
ActiveOptions
Options for determining when the link is active.
activeOptions={{
  exact: true,
  includeSearch: true,
  includeHash: false
}}
​
activeProps
React.AnchorHTMLAttributes
Props to apply when the link is active.
activeProps={{
  className: 'font-bold text-blue-600',
  'aria-current': 'page'
}}
​
inactiveProps
React.AnchorHTMLAttributes
Props to apply when the link is inactive.
inactiveProps={{
  className: 'text-gray-600'
}}

​
ActiveOptions

Options for determining link active state.
​
exact
boolean
Match the path exactly.Default: false
​
includeHash
boolean
Include hash in active matching.Default: false
​
includeSearch
boolean
Include search params in active matching.Default: false
The primary navigation component. 
import { Link } from '@tanstack/react-router'

function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link 
        to="/posts" 
        activeProps={{ className: 'active' }}
      >
        Posts
      </Link>
      <Link 
        to="/posts/$postId" 
        params={{ postId: '123' }}
        search={{ tab: 'comments' }}
      >
        Post Details
      </Link>
    </nav>
  )
}

​
useLinkProps Hook

Generate props for custom link components. 
import { useLinkProps } from '@tanstack/react-router'

function CustomLink(props) {
  const linkProps = useLinkProps(props)
  
  return (
    <a {...linkProps} className="custom-link">
      {props.children}
    </a>
  )
}
Create custom link components with default props. 
import { createLink } from '@tanstack/react-router'

const ButtonLink = createLink('button')

function Navigation() {
  return (
    <ButtonLink 
      to="/posts"
      className="btn btn-primary"
    >
      View Posts
    </ButtonLink>
  )
}
With custom component: 
const IconLink = createLink(
  React.forwardRef((props, ref) => (
    <a ref={ref} {...props}>
      <Icon />
      {props.children}
    </a>
  ))
)
Programmatic navigation function. 
import { useNavigate } from '@tanstack/react-router'

function LoginButton() {
  const navigate = useNavigate()
  
  const handleLogin = async () => {
    await login()
    
    await navigate({
      to: '/dashboard',
      replace: true
    })
  }
  
  return <button onClick={handleLogin}>Login</button>
}
Declarative navigation component. 
import { Navigate } from '@tanstack/react-router'

function ProtectedRoute() {
  const { user } = useAuth()
  
  if (!user) {
    return <Navigate to="/login" />
  }
  
  return <Dashboard />
}

​
linkOptions Helper

Type-safe link options without rendering. 
import { linkOptions } from '@tanstack/react-router'

const postLinkOptions = linkOptions({
  to: '/posts/$postId',
  params: { postId: '123' }
})

// Use with Link
<Link {...postLinkOptions}>View Post</Link>

// Use with navigate
await navigate(postLinkOptions)

​
Examples

​
Basic Navigation

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

function Header() {
  return (
    <header>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/contact">Contact</Link>
    </header>
  )
}

<Link
  to="/posts"
  activeProps={{
    className: 'font-bold text-blue-600',
    style: { textDecoration: 'underline' }
  }}
  activeOptions={{
    exact: false,
    includeSearch: false
  }}
>
  Posts
</Link>

​
Relative Navigation

function PostNavigation() {
  return (
    <nav>
      <Link to=".">Current Post</Link>
      <Link to="./edit">Edit</Link>
      <Link to="../">All Posts</Link>
    </nav>
  )
}

​
Search Params

<Link
  to="/posts"
  search={(prev) => ({
    ...prev,
    page: (prev.page || 0) + 1
  })}
>
  Next Page
</Link>

​
Preloading

<Link
  to="/posts/$postId"
  params={{ postId: '123' }}
  preload="intent"
  preloadDelay={100}
>
  View Post (preloads on hover)
</Link>

import { createLink, LinkComponent } from '@tanstack/react-router'

const MyLink: LinkComponent = createLink(
  React.forwardRef((props, ref) => {
    const isExternal = props.href?.startsWith('http')
    
    return (
      <a
        ref={ref}
        {...props}
        className={`link ${props.className || ''}`}
        {...(isExternal && {
          target: '_blank',
          rel: 'noopener noreferrer'
        })}
      >
        {props.children}
        {isExternal && ' ↗'}
      </a>
    )
  })
)

function ItemsList() {
  return (
    <div>
      {items.map(item => (
        <Link
          key={item.id}
          to="/items/$itemId"
          params={{ itemId: item.id }}
          state={{ from: 'list' }}
        >
          {item.name}
        </Link>
      ))}
    </div>
  )
}

​
Programmatic Navigation

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

function CreatePostForm() {
  const navigate = useNavigate()
  
  const handleSubmit = async (data) => {
    const post = await createPost(data)
    
    await navigate({
      to: '/posts/$postId',
      params: { postId: post.id },
      search: { success: true },
      replace: true
    })
  }
  
  return <form onSubmit={handleSubmit}>...</form>
}

Build docs developers (and LLMs) love

Get started for freeTalk to us