> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tanstack/router/llms.txt
> Use this file to discover all available pages before exploring further.
# Link
# Link API
Components and utilities for type-safe navigation.
## `Link`
A strongly-typed anchor component for declarative navigation.
```tsx theme={null}
import { Link } from '@tanstack/react-router'
function Navigation() {
return (
View Post
)
}
```
### Props
The destination route path. Can be absolute (`/posts`) or relative (`./edit`, `..`).
Path parameters for the destination route.
```tsx theme={null}
View Post
```
Search parameters for the destination route. Can be an object or an updater function.
```tsx theme={null}
Page 2
{/* Updater function */}
({ ...prev, page: prev.page + 1 })}>
Next Page
```
The hash fragment for the destination URL.
```tsx theme={null}
Installation
```
State to pass to the destination route.
```tsx theme={null}
Posts
```
The source route path for relative navigation. Defaults to the current route.
```tsx theme={null}
About
```
Controls route preloading behavior.
* `false` - Don't preload
* `'intent'` - Preload on hover/focus
* `'viewport'` - Preload when link enters viewport
* `'render'` - Preload on render
```tsx theme={null}
Posts
```
Delay in milliseconds before preloading on hover/focus.
```tsx theme={null}
Posts
```
Additional props to apply when the link is active.
```tsx theme={null}
Posts
```
Additional props to apply when the link is inactive.
```tsx theme={null}
Posts
```
Options for determining when the link is active.
```tsx theme={null}
Posts
```
If `true`, the link will only be active if the pathname matches exactly.
If `true`, the link's search params must match the current location's search params.
If `true`, the link's hash must match the current location's hash.
If `true`, the link will be disabled and not navigate.
```tsx theme={null}
Posts
```
If `true`, the navigation will replace the current history entry instead of pushing a new one.
```tsx theme={null}
Posts
```
If `true`, the scroll position will be reset to the top of the page on navigation.
```tsx theme={null}
Posts
```
If `true`, the navigation will use the View Transitions API if available.
```tsx theme={null}
Posts
```
Options for masking the URL (showing a different URL in the address bar).
```tsx theme={null}
View Photo
```
### Children
The Link component accepts children as React nodes or a render function:
```tsx theme={null}
{/* Static children */}
View Posts
{/* Render function */}
{({ isActive, isTransitioning }) => (
Posts {isTransitioning && '...'}
)}
```
## `createLink`
Creates a typed Link-like component that preserves TanStack Router's navigation semantics.
```tsx theme={null}
import { createLink } from '@tanstack/react-router'
import { forwardRef } from 'react'
const MyLink = forwardRef((props, ref) => {
return
})
const CustomLink = createLink(MyLink)
function Navigation() {
return (
View Post
)
}
```
### Parameters
The host component to render (e.g., a design-system Link/Button).
### Returns
A router-aware component with the same API as `Link`.
## `useLinkProps`
Build anchor-like props for declarative navigation and preloading.
```tsx theme={null}
import { useLinkProps } from '@tanstack/react-router'
function CustomLink({ to, ...props }) {
const linkProps = useLinkProps({ to })
return
}
```
### Parameters
Link options (same as Link props).
Includes all the same options as `Link`: `to`, `params`, `search`, `hash`, `state`, `preload`, `activeProps`, etc.
Optional forwarded ref for the link element.
### Returns
React anchor props suitable for `` 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`.
```tsx theme={null}
import { linkOptions } from '@tanstack/react-router'
const postLinkOpts = linkOptions({
to: '/posts/$postId',
params: { postId: '123' },
search: { tab: 'comments' },
})
function Navigation() {
return View Post
}
function SomeComponent() {
const navigate = useNavigate()
const goToPost = () => navigate(postLinkOpts)
return
}
```
### Parameters
Literal options object for navigation.
### Returns
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:
```tsx theme={null}
Posts
```
The link will have `data-status="active"` and `aria-current="page"` attributes when active.
### Preloading
Links can preload routes before navigation:
```tsx theme={null}
{/* Preload on hover/focus */}
Posts
{/* Preload when visible */}
Posts
{/* Preload on render */}
Posts
```
### Relative Navigation
```tsx theme={null}
{/* Navigate to parent */}
Back
{/* Navigate to sibling */}
Other
{/* Navigate to child */}
Edit
{/* Stay on current route, update search */}
Page 2
```