Link

The Link component provides strongly-typed declarative navigation with built-in preloading and active state management.

Link Component

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:

Show ActiveOptions properties

exact · boolean · default: "false"

Match the exact path only.

includeSearch · boolean · default: "true"

Include search params in active matching.

includeHash · boolean · default: "false"

Include hash in active matching.

explicitUndefined · boolean · default: "false"

Treat undefined search params as explicitly set.

<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

createLink Function

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>

External Links

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

Custom Link Component

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

• Navigation Guide
• useNavigate Hook
• Preloading Guide