Skip to main content
The Link component provides strongly-typed declarative navigation with built-in preloading and active state management. A strongly-typed anchor component for declarative navigation. 
import { Link } from '@tanstack/react-router'

function Nav() {
  return (
    <Link to="/posts/$postId" params={{ postId: '123' }}>
      View Post
    </Link>
  )
}
Source: packages/react-router/src/link.tsx:925-945

​
Props

​
to
string
required
The destination route path. Can be absolute (/posts) or relative (./post).
​
params
TParams
Path parameters for the destination route. Type-safe based on the to path.
<Link to="/posts/$postId" params={{ postId: '123' }} />
​
search
TSearch
Search parameters for the destination. Type-safe based on route’s search schema.
<Link to="/posts" search={{ page: 1, filter: 'new' }} />
​
hash
string
Hash fragment for the destination (e.g., #section-1).
<Link to="/docs" hash="introduction" />
​
state
TState
State object to pass to the destination location.
<Link to="/posts" state={{ from: 'home' }} />
​
replace
boolean
default:"false"
Replace the current history entry instead of pushing a new one.
<Link to="/login" replace />
​
resetScroll
boolean
default:"true"
Reset scroll position to top on navigation.
<Link to="/about" resetScroll={false} />
​
from
string
The route to navigate from. Used for relative navigation and type inference.
<Link from="/posts" to="./new" />

​
Preloading Props

​
preload
'intent' | 'render' | 'viewport' | boolean
default:"false"
Controls route preloading strategy:
  • 'intent': Preload on hover or focus
  • 'render': Preload when link renders
  • 'viewport': Preload when link enters viewport
  • true: Alias for ‘intent’
  • false: Disable preloading
<Link to="/posts" preload="intent" />
​
preloadDelay
number
default:"0"
Delay in milliseconds before preloading on hover/focus.
<Link to="/posts" preload="intent" preloadDelay={100} />

​
Active State Props

​
activeProps
React.AnchorHTMLAttributes | () => React.AnchorHTMLAttributes
Props to apply when the link is active. Styles and classNames are merged.
<Link
  to="/about"
  activeProps={{
    className: 'font-bold',
    style: { color: 'blue' },
  }}
/>
​
inactiveProps
React.AnchorHTMLAttributes | () => React.AnchorHTMLAttributes
Props to apply when the link is inactive.
<Link
  to="/about"
  inactiveProps={{
    className: 'text-gray-500',
  }}
/>
​
activeOptions
ActiveOptions
Options for determining active state:
<Link
  to="/posts"
  activeOptions={{ exact: true, includeSearch: false }}
/>

​
Advanced Props

​
mask
MaskOptions
Mask the URL shown in the browser while navigating to a different route.
<Link
  to="/posts/$postId"
  params={{ postId: '123' }}
  mask={{ to: '/p/$id', params: { id: '123' } }}
/>
​
disabled
boolean
default:"false"
Disable the link (prevents navigation and preloading).
<Link to="/premium" disabled={!isPremium} />
​
target
string
Standard anchor target attribute (_blank, _self, etc.).
​
reloadDocument
boolean
default:"false"
Perform a full page reload instead of client-side navigation.
​
viewTransition
boolean
Use View Transitions API for navigation animation.
​
startTransition
boolean
Wrap navigation in React.startTransition.
​
ignoreBlocker
boolean
default:"false"
Bypass any registered navigation blockers.
​
hashScrollIntoView
boolean | ScrollIntoViewOptions
default:"true"
Control automatic scrolling to hash target.

​
Children

​
children
React.ReactNode | (state) => React.ReactNode
Link content. Can be a render function receiving active state.
<Link to="/posts">
  {({ isActive, isTransitioning }) => (
    <span className={isActive ? 'active' : ''}>
      Posts {isTransitioning && '...'}
    </span>
  )}
</Link>

​
Data Attributes

The Link component automatically sets these data attributes:
  • data-status="active" - When the link is active
  • aria-current="page" - When the link is active
  • data-transitioning="transitioning" - During navigation transition

​
useLinkProps Hook

Build anchor-like props for declarative navigation and preloading. 
import { useLinkProps } from '@tanstack/react-router'

function CustomLink(props) {
  const linkProps = useLinkProps(props)
  return <a {...linkProps} className="custom" />
}
Source: packages/react-router/src/link.tsx:43-719
​
options
UseLinkPropsOptions
required
Same options as Link props.
​
forwardedRef
React.ForwardedRef<Element>
Ref to forward to the element.
​
returns
React.ComponentPropsWithRef<'a'>
React anchor props suitable for <a> or custom components including:
  • href - Computed URL
  • Event handlers (onClick, onMouseEnter, etc.)
  • Accessibility props (aria-current, role, etc.)
  • Active/inactive className and style merged
Creates a typed Link-like component with custom rendering. 
import { createLink } from '@tanstack/react-router'
import { DesignSystemLink } from './design-system'

const CustomLink = createLink(DesignSystemLink)

// Use like Link with custom styling
<CustomLink to="/posts" params={{ postId: '123' }} />
Source: packages/react-router/src/link.tsx:901-907
​
Comp
React.Component
required
The host component to render (e.g., a design-system Link/Button).
​
returns
LinkComponent
A router-aware component with the same API as Link.

​
linkOptions Function

Validate and reuse navigation options for Link, navigate or redirect. 
import { linkOptions } from '@tanstack/react-router'

const postLinkOpts = linkOptions({
  to: '/posts/$postId',
  params: { postId: '123' },
  search: { tab: 'comments' },
})

// Reuse in multiple places
<Link {...postLinkOpts} />
navigate(postLinkOpts)
Source: packages/react-router/src/link.tsx:974-976
​
options
LinkOptions
required
Navigation options object.
​
returns
LinkOptions
The same options object, but type-checked.

​
Usage Examples

​
Basic Navigation

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

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/posts">Posts</Link>
    </nav>
  )
}

​
With Parameters

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

​
With Search Parameters

<Link 
  to="/posts" 
  search={{ page: 2, filter: 'recent' }}
>
  Recent Posts (Page 2)
</Link>

​
Active Styling

<Link
  to="/dashboard"
  activeProps={{
    className: 'font-bold text-blue-600',
  }}
  activeOptions={{ exact: true }}
>
  Dashboard
</Link>

​
With Preloading

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

​
Relative Navigation

// From /posts/123
<Link to="./edit">Edit</Link> // → /posts/123/edit
<Link to="..">Back to Posts</Link> // → /posts

​
With Children Function

<Link to="/settings">
  {({ isActive, isTransitioning }) => (
    <>
      <SettingsIcon />
      Settings
      {isActive && <Badge>Active</Badge>}
      {isTransitioning && <Spinner />}
    </>
  )}
</Link>

// Automatically detected as external
<Link to="https://tanstack.com">TanStack</Link>

// Or with target
<Link to="https://github.com/tanstack/router" target="_blank">
  GitHub
</Link>

​
With URL Masking

<Link
  to="/posts/$postId"
  params={{ postId: '123' }}
  mask={{
    to: '/p/$id',
    params: { id: '123' },
  }}
>
  View Post
</Link>
// Navigates to /posts/123 but shows /p/123 in URL

import { createLink } from '@tanstack/react-router'
import { Button } from './ui/button'

const ButtonLink = createLink(Button)

function Nav() {
  return (
    <ButtonLink to="/dashboard" variant="primary">
      Go to Dashboard
    </ButtonLink>
  )
}

​
Programmatic Props

function ConditionalLink({ canEdit, postId }) {
  return (
    <Link
      to="/posts/$postId"
      params={{ postId }}
      disabled={!canEdit}
      activeProps={() => ({
        style: { 
          color: canEdit ? 'blue' : 'gray' 
        }
      })}
    >
      Edit Post
    </Link>
  )
}

​
Type Safety

Link provides full type safety for:
  • Route paths: Autocomplete and validation of to prop
  • Parameters: Type-checked based on the destination route
  • Search params: Validated against route’s search schema
  • Relative navigation: Correct types based on from prop
// TypeScript will error if params don't match
<Link 
  to="/posts/$postId" 
  params={{ wrongParam: '123' }} // ❌ Error
/>

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

​
Performance

The Link component is optimized for performance:
  • Automatic code splitting: Routes are lazy-loaded on demand
  • Smart preloading: Load routes before navigation with configurable strategies
  • Minimal re-renders: Only updates when active state changes
  • SSR-safe: Renders correct href on server, hydrates without mismatch

​
Accessibility

Link follows accessibility best practices:
  • Renders semantic <a> elements
  • Sets aria-current="page" when active
  • Preserves standard anchor attributes (target, rel, etc.)
  • Supports keyboard navigation
  • Works with screen readers

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us