navigation — Claude Code skill: navigation and install
This skill guides TanStack Router navigation with links, programmatic transitions, route preloading, and protection against leaving dirty forms.
MIT 214 installs ★ 15,341 updated 2026-10-25
npx skills add TanStack/router --skill navigation -a claude-codeWhat navigation does
The skill covers TanStack Router navigation through Link, useNavigate, Navigate, and router.navigate. It explains how to combine to, params, and from for typed and relative routes, style active links with activeOptions and activeProps, and reuse checked navigation objects through linkOptions and createLink.
It also covers intent, viewport, and render preloading, preloadDelay, manual calls to router.preloadRoute, scroll restoration, and MatchRoute. Unsaved form changes can be handled with useBlocker, Block, or a custom confirmation flow. router-core is required before using the skill.
The skill can be installed for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. For Claude Code, the installed file is ~/.claude/skills/navigation/SKILL.md.
What it helps with
- create typed links with route parameters
- redirect after a form submission
- mark the current navigation item
- preload a route on intent or viewport entry
- stop navigation when a form has unsaved changes
Example prompts for the agent
- Set up a typed link to
/posts/$postIdand pass itspostIdparameter. - Add intent-based preloading with
preloadDelayto a post link. - Show how to block navigation for a dirty form with
useBlocker.
How to install navigation
1Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a claude-code2Manually: put the files in place
~/.claude/skills/navigation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/navigation/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a codex2Manually: put the files in place
.agents/skills/navigation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a cursor2Manually: put the files in place
.cursor/skills/navigation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/navigation2Manually: put the files in place
.github/skills/navigation/SKILL.md1Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a gemini-cli2Platform CLI
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/navigationManually: put the files in place
.devin/skills/navigation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about navigation
How do I install navigation in Claude Code?
Run npx skills add TanStack/router --skill navigation -a claude-code, then use ~/.claude/skills/navigation/SKILL.md.
What does navigation do?
It guides the agent through TanStack Router links, code-driven transitions, relative paths, active link state, route preloading, and navigation blocking.
What does navigation require?
The skill requires router-core. Its preloading guidance covers intent, viewport, and render strategies.
Source text
SKILL.md · MIT
---
name: navigation
description: >-
Link component, useNavigate, Navigate component, router.navigate,
ToOptions/NavigateOptions/LinkOptions, from/to relative navigation,
activeOptions/activeProps, preloading (intent/viewport/render),
preloadDelay, navigation blocking (useBlocker, Block), createLink,
linkOptions helper, scroll restoration, MatchRoute.
metadata:
type: sub-skill
library: tanstack-router
library_version: '1.171.15'
requires:
- router-core
sources:
- TanStack/router:docs/router/guide/navigation.md
- TanStack/router:docs/router/guide/preloading.md
- TanStack/router:docs/router/guide/navigation-blocking.md
- TanStack/router:docs/router/guide/link-options.md
- TanStack/router:docs/router/guide/custom-link.md
- TanStack/router:docs/router/guide/scroll-restoration.md
---
# Navigation
## Setup
Basic type-safe `Link` with `to` and `params`:
```tsx
import { Link } from '@tanstack/react-router'
function PostLink({ postId }: { postId: string }) {
return (
<Link to="/posts/$postId" params={{ postId }}>
View Post
</Link>
)
}
```
## Core Patterns
### Link with Active States
```tsx
import { Link } from '@tanstack/react-router'
function NavLink() {
return (
<Link
to="/posts"
activeProps={{ className: 'font-bold' }}
inactiveProps={{ className: 'text-gray-500' }}
activeOptions={{ exact: true }}
>
Posts
</Link>
)
}
```
The `data-status` attribute is also set to `"active"` on active links for CSS-based styling.
`activeOptions` controls matching behavior:
- `exact` (default `false`) — when `true`, only matches the exact path (not children)
- `includeHash` (default `false`) — include hash in active matching
- `includeSearch` (default `true`) — include search params in active matching
Children can receive `isActive` as a render function:
```tsx
<Link to="/posts">
{({ isActive }) => <span className={isActive ? 'font-bold' : ''}>Posts</span>}
</Link>
```
### Relative Navigation with `from`
Without `from`, navigation resolves from root `/`. To use relative paths like `..`, provide `from`:
```tsx
import { createFileRoute, Link } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
component: PostComponent,
})
function PostComponent() {
return (
<div>
{/* Relative to current route */}
<Link from={Route.fullPath} to="..">
Back to Posts
</Link>
{/* "." reloads the current route */}
<Link from={Route.fullPath} to=".">
Reload
</Link>
</div>
)
}
```
### useNavigate for Programmatic Navigation
Use `useNavigate` only for side-effect-driven navigation (e.g., after a form submission). For anything the user clicks, prefer `Link`.
```tsx
import { useNavigate } from '@tanstack/react-router'
function CreatePostForm() {
const navigate = useNavigate({ from: '/posts' })
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
const response = await fetch('/api/posts', { method: 'POST', body: '...' })
const { id: postId } = await response.json()
if (response.ok) {
navigate({ to: '/posts/$postId', params: { postId } })
}
}
return <form onSubmit={handleSubmit}>{/* ... */}</form>
}
```
The `Navigate` component performs an immediate client-side navigation on mount:
```tsx
import { Navigate } from '@tanstack/react-router'
function LegacyRedirect() {
return <Navigate to="/posts/$postId" params={{ postId: 'my-first-post' }} />
}
```
`router.navigate` is available anywhere you have the router instance, including outside of React.
### Preloading
Strategies: `intent` (hover/touchstart), `viewport` (intersection observer), `render` (on mount).
Set globally:
```tsx
import { createRouter } from '@tanstack/react-router'
const router = createRouter({
routeTree,
defaultPreload: 'intent',
defaultPreloadDelay: 50, // ms, default is 50
})
```
Or per-link:
```tsx
<Link
to="/posts/$postId"
params={{ postId }}
preload="intent"
preloadDelay={100}
>
View Post
</Link>
```
Preloaded data stays fresh for 30 seconds by default (`defaultPreloadStaleTime: 30_000`). During that window it won't be refetched. When using an external cache like TanStack Query, set `defaultPreloadStaleTime: 0` to let the external library control freshness.
Manual preloading via the router instance:
```tsx
import { useRouter } from '@tanstack/react-router'
function Component() {
const router = useRouter()
useEffect(() => {
router.preloadRoute({ to: '/posts/$postId', params: { postId: '1' } })
}, [router])
return <div />
}
```
### Navigation Blocking
Use `useBlocker` to prevent navigation when a form has unsaved changes:
```tsx
import { useBlocker } from '@tanstack/react-router'
import { useState } from 'react'
function EditForm() {
const [formIsDirty, setFormIsDirty] = useState(false)
useBlocker({
shouldBlockFn: () => {
if (!formIsDirty) return false
const shouldLeave = confirm('Are you sure you want to leave?')
return !shouldLeave
},
})
return <form>{/* ... */}</form>
}
```
With custom UI using `withResolver`:
```tsx
import { useBlocker } from '@tanstack/react-router'
import { useState } from 'react'
function EditForm() {
const [formIsDirty, setFormIsDirty] = useState(false)
const { proceed, reset, status } = useBlocker({
shouldBlockFn: () => formIsDirty,
withResolver: true,
})
return (
<>
<form>{/* ... */}</form>
{status === 'blocked' && (
<div>
<p>Are you sure you want to leave?</p>
<button onClick={proceed}>Yes</button>
<button onClick={reset}>No</button>
</div>
)}
</>
)
}
```
Control `beforeunload` separately:
```tsx
useBlocker({
shouldBlockFn: () => formIsDirty,
enableBeforeUnload: formIsDirty,
})
```
### linkOptions for Reusable Navigation Options
`linkOptions` provides eager type-checking on navigation options objects, so errors surface at definition, not at spread-site:
```tsx
import {
linkOptions,
Link,
useNavigate,
redirect,
} from '@tanstack/react-router'
const dashboardLinkOptions = linkOptions({
to: '/dashboard',
search: { search: '' },
})
// Use anywhere: Link, navigate, redirect
function Nav() {
const navigate = useNavigate()
return (
<div>
<Link {...dashboardLinkOptions}>Dashboard</Link>
<button onClick={() => navigate(dashboardLinkOptions)}>Go</button>
</div>
)
}
// Also works in an array for navigation bars
const navOptions = linkOptions([
{ to: '/dashboard', label: 'Summary', activeOptions: { exact: true } },
{ to: '/dashboard/invoices', label: 'Invoices' },
{ to: '/dashboard/users', label: 'Users' },
])
function NavBar() {
return (
<nav>
{navOptions.map((option) => (
<Link
{...option}
key={option.to}
activeProps={{ className: 'font-bold' }}
>
{option.label}
</Link>
))}
</nav>
)
}
```
### createLink for Custom Components
Wraps any component with TanStack Router's type-safe navigation:
```tsx
import * as React from 'react'
import { createLink, LinkComponent } from '@tanstack/react-router'
interface BasicLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {}
const BasicLinkComponent = React.forwardRef<HTMLAnchorElement, BasicLinkProps>(
(props, ref) => {
return <a ref={ref} {...props} className="block px-3 py-2 text-blue-700" />
},
)
const CreatedLinkComponent = createLink(BasicLinkComponent)
export const CustomLink: LinkComponent<typeof BasicLinkComponent> = (props) => {
return <CreatedLinkComponent preload="intent" {...props} />
}
```
Usage retains full type safety:
```tsx
<CustomLink to="/dashboard/invoices/$invoiceId" params={{ invoiceId: 0 }} />
```
### Scroll Restoration
Enable globally on the router:
```tsx
const router = createRouter({
routeTree,
scrollRestoration: true,
})
```
For nested scrollable areas:
```tsx
const router = createRouter({
routeTree,
scrollRestoration: true,
scrollToTopSelectors: ['#main-scrollable-area'],
})
```
Custom cache keys:
```tsx
const router = createRouter({
routeTree,
scrollRestoration: true,
getScrollRestorationKey: (location) => location.pathname,
})
```
Prevent scroll reset for a specific navigation:
```tsx
<Link to="/posts" resetScroll={false}>
Posts
</Link>
```
### MatchRoute for Pending UI
```tsx
import { Link, MatchRoute } from '@tanstack/react-router'
function Nav() {
return (
<Link to="/users">
Users
<MatchRoute to="/users" pending>
<Spinner />
</MatchRoute>
</Link>
)
}
```
## Common Mistakes
### CRITICAL: Interpolating params into the `to` string
```tsx
// WRONG — breaks type safety and param encoding
<Link to={`/posts/${postId}`}>Post</Link>
// CORRECT — use the params option
<Link to="/posts/$postId" params={{ postId }}>Post</Link>
```
Dynamic segments are declared with `$` in the route path. Always pass them via `params`. This applies to `Link`, `useNavigate`, `Navigate`, and `router.navigate`.
### MEDIUM: Using useNavigate for clickable elements
```tsx
// WRONG — no href, no cmd+click, no preloading, no accessibility
function BadNav() {
const navigate = useNavigate()
return <button onClick={() => navigate({ to: '/posts' })}>Posts</button>
}
// CORRECT — real <a> tag with href, accessible, preloadable
function GoodNav() {
return <Link to="/posts">Posts</Link>
}
```
Use `useNavigate` only for programmatic side-effect navigation (after form submit, async action, etc).
### HIGH: Not providing `from` for relative navigation
```tsx
// WRONG — without from, ".." resolves from root
<Link to="..">Back</Link>
// CORRECT — provide from for relative resolution
<Link from={Route.fullPath} to="..">Back</Link>
```
Without `from`, only absolute paths are autocompleted and type-safe. Relative paths like `..` resolve from root instead of the current route.
### HIGH: Using search as object instead of function loses existing params
```tsx
// WRONG — replaces ALL search params with just { page: 2 }
<Link to="." search={{ page: 2 }}>Page 2</Link>
// CORRECT — preserves existing search params, updates page
<Link to="." search={(prev) => ({ ...prev, page: 2 })}>Page 2</Link>
```
When you pass `search` as a plain object, it replaces all search params. Use the function form to spread previous params and selectively update.
---
## Cross-References
- See also: **router-core/search-params/SKILL.md** — Link `search` prop interacts with search param validation
- See also: **router-core/type-safety/SKILL.md** — `from` narrowing improves type inference on Link
© TanStack · MIT · TanStack/router