Link

Link API

Components and utilities for type-safe navigation.

Link

A strongly-typed anchor component for declarative navigation.

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

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

Props

to · string · required

The destination route path. Can be absolute (/posts) or relative (./edit, ..).

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 destination route. Can be an object or an updater function.

<Link to="/posts" search={{ page: 2, filter: 'active' }}>
  Page 2
</Link>

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

hash · string | function

The hash fragment for the destination URL.

<Link to="/docs" hash="#installation">
  Installation
</Link>

state · object | function

State to pass to the destination route.

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

from · string

The source route path for relative navigation. Defaults to the current route.

<Link from="/posts" to="/about">
  About
</Link>

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

Controls route preloading behavior.

• false - Don’t preload
• 'intent' - Preload on hover/focus
• 'viewport' - Preload when link enters viewport
• 'render' - Preload on render

<Link to="/posts" preload="viewport">
  Posts
</Link>

preloadDelay · number

Delay in milliseconds before preloading on hover/focus.

<Link to="/posts" preload="intent" preloadDelay={100}>
  Posts
</Link>

activeProps · object | function

Additional props to apply when the link is active.

<Link
  to="/posts"
  activeProps={{
    className: 'font-bold',
    style: { color: 'blue' },
  }}
>
  Posts
</Link>

inactiveProps · object | function

Additional props to apply when the link is inactive.

<Link
  to="/posts"
  inactiveProps={{
    className: 'text-gray-500',
  }}
>
  Posts
</Link>

activeOptions · object

Options for determining when the link is active.

<Link
  to="/posts"
  activeOptions={{
    exact: true,
    includeSearch: true,
    includeHash: false,
  }}
>
  Posts
</Link>

Show properties

exact · boolean · default: "false"

If true, the link will only be active if the pathname matches exactly.

includeSearch · boolean · default: "true"

If true, the link’s search params must match the current location’s search params.

includeHash · boolean · default: "false"

If true, the link’s hash must match the current location’s hash.

disabled · boolean

If true, the link will be disabled and not navigate.

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

replace · boolean

If true, the navigation will replace the current history entry instead of pushing a new one.

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

resetScroll · boolean

If true, the scroll position will be reset to the top of the page on navigation.

<Link to="/posts" resetScroll={false}>
  Posts
</Link>

viewTransition · boolean

If true, the navigation will use the View Transitions API if available.

<Link to="/posts" viewTransition>
  Posts
</Link>

mask · object

Options for masking the URL (showing a different URL in the address bar).

<Link
  to="/photos/$photoId"
  params={{ photoId: '123' }}
  mask={{
    to: '/photos',
  }}
>
  View Photo
</Link>

Children

The Link component accepts children as React nodes or a render function:

{/* Static children */}
<Link to="/posts">View Posts</Link>

{/* Render function */}
<Link to="/posts">
  {({ isActive, isTransitioning }) => (
    <span className={isActive ? 'active' : ''}>
      Posts {isTransitioning && '...'}
    </span>
  )}
</Link>

createLink

Creates a typed Link-like component that preserves TanStack Router’s navigation semantics.

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

const MyLink = forwardRef<HTMLAnchorElement, any>((props, ref) => {
  return <a ref={ref} {...props} className={`my-link ${props.className}`} />
})

const CustomLink = createLink(MyLink)

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

Parameters

Comp · Component · required

The host component to render (e.g., a design-system Link/Button).

Returns

LinkComponent · Component

A router-aware component with the same API as Link.

useLinkProps

Build anchor-like props for declarative navigation and preloading.

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

function CustomLink({ to, ...props }) {
  const linkProps = useLinkProps({ to })
  return <a {...linkProps} {...props} />
}

Parameters

options · UseLinkPropsOptions · required

Link options (same as Link props).

Includes all the same options as Link: to, params, search, hash, state, preload, activeProps, etc.

forwardedRef · React.ForwardedRef<Element>

Optional forwarded ref for the link element.

Returns

props · React.ComponentPropsWithRef<'a'>

React anchor props suitable for <a> or custom components, including:

• href - The computed URL
• onClick - Navigation handler
• onMouseEnter, onFocus, etc. - Preload handlers
• data-status - ‘active’ if the link is active
• aria-current - ‘page’ if the link is active
• Additional props from activeProps or inactiveProps

linkOptions

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

function Navigation() {
  return <Link {...postLinkOpts}>View Post</Link>
}

function SomeComponent() {
  const navigate = useNavigate()
  const goToPost = () => navigate(postLinkOpts)
  return <button onClick={goToPost}>Go to Post</button>
}

Parameters

options · LinkOptions · required

Literal options object for navigation.

Returns

options · LinkOptions

The same options object, but typed for later spreading into Link, navigate, or redirect.

Navigation Behavior

Active State

Links automatically detect when they match the current route and apply active styling:

<Link
  to="/posts"
  activeProps={{ className: 'font-bold text-blue-500' }}
  inactiveProps={{ className: 'text-gray-500' }}
>
  Posts
</Link>

The link will have data-status="active" and aria-current="page" attributes when active.

Preloading

Links can preload routes before navigation:

{/* Preload on hover/focus */}
<Link to="/posts" preload="intent">
  Posts
</Link>

{/* Preload when visible */}
<Link to="/posts" preload="viewport">
  Posts
</Link>

{/* Preload on render */}
<Link to="/posts" preload="render">
  Posts
</Link>

Relative Navigation

{/* Navigate to parent */}
<Link to="..">
  Back
</Link>

{/* Navigate to sibling */}
<Link to="../other">
  Other
</Link>

{/* Navigate to child */}
<Link to="./edit">
  Edit
</Link>

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