Link API

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

Link Component

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>
  )
}

createLink Function

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>
  ))
)

Navigate Function

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>
}

Navigate Component

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>
  )
}

Active Link Styling

<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>

Custom Link Component

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>
    )
  })
)

Navigation with State

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>
}