Link between typed routes
Application navigation
TanStack · Component
Link
TanStack Router's Link creates typed, declarative navigation to a new location. It renders a real anchor with a valid href and supports route parameters, search parameters, hashes, state, active styling, and preloading.
How it works
Link is a typed navigation component for TanStack Router. It produces an anchor with a usable href, while its options describe the destination pathname, route parameters, search parameters, hash, and location state.
Syntax
<Link to="/route" params={{ ... }} search={{ ... }}>Children</Link>Parameters
| Name | Type | Description |
|---|---|---|
to | string | Destination route pathname; it may contain route placeholders. |
params | object or updater function | Values used to fill dynamic route parameters. |
search | object, boolean, or updater function | Search parameters, supplied as a value or updater from previous search state. |
from | string | Optional route origin used when resolving relative links. |
preload | false | 'intent' | 'viewport' | 'render' | Controls when route data is preloaded. |
Returns
An anchor element that can be used to navigate to a new location.
Key points
- Use Link for declarative navigation between locations in a TanStack Router application.
- A link can describe changes to the pathname, query string, hash, and navigation state.
- The component outputs a real anchor and href, retaining standard browser link behavior.
- Normal anchor attributes, including target, can be used for browser behaviors such as opening a new window.
- activeProps and inactiveProps allow link properties to vary according to whether the destination is active.
- Preloading can be configured with false, intent, viewport, or render.
Common mistakes
- Route parameter values containing characters such as @ are encoded by default, so the resulting URL may differ from the raw value.
- Relative navigation depends on the supplied from route; without it, relative paths resolve from the current active location.
- The path-parameter character setting must be chosen when creating the router and cannot be modified afterward.
Example: Typed route link
import { Link } from '@tanstack/react-router'
export function Navigation() {
return (
<nav>
<Link
to="/somewhere/$somewhereId"
params={{ somewhereId: 'baz' }}
search={(prev) => ({ ...prev, foo: 'bar' })}
>
Go to item
</Link>
</nav>
)
}This renders a typed anchor that navigates to a route with a path parameter and updates search parameters.
When to use it
Fill route parameters
Dynamic pages
Update search parameters
Filtered views
Preload a destination before activation
Prefetching
Interview questions
QWhat does the Link component render and why is that useful?
Link renders an actual anchor with a valid href, so users can click it or open it with modifier keys. It also supplies TanStack Router's typed navigation options for route-aware navigation.
Follow-up: When should useNavigate be preferred? Use it when navigation must happen imperatively as a side effect; otherwise, the Link component is generally preferred.
QWhich navigation data can Link express?
The destination can include a pathname, route parameters, search parameters, hash, and location state. Route parameters are passed through the params option, while search can be an object or a function derived from previous values.
Follow-up: How can a link preserve existing search parameters? Pass search={true}, or return the previous search object from a functional search option.
QHow does Link preloading work?
Link supports four preload modes: false, intent, viewport, and render. Intent preloads on focus, hover, or touch; viewport preloads when entering the viewport; render preloads immediately after rendering.
Follow-up: What is a practical conservative default? Keep automatic preloading disabled with false when prefetching is not wanted.
Related
useNavigateLinkPropsactivePropsinactivePropspathParamsAllowedCharacters