navigation — скилл для Claude Code: навигация и установка
Скилл navigation помогает агенту настраивать навигацию в TanStack Router: ссылки, переходы, предзагрузку маршрутов и блокировку ухода со страницы.
MIT 214 установок ★ 15 341 обновлён 2026-10-25
npx skills add TanStack/router --skill navigation -a claude-codeЧто делает navigation
Скилл охватывает навигацию в TanStack Router через Link, useNavigate, Navigate и router.navigate. Он подсказывает, как задавать to, params и from, строить относительные переходы, отмечать активные ссылки через activeOptions и activeProps, а также переиспользовать параметры с linkOptions и createLink.
Внутри также разобраны стратегии предзагрузки intent, viewport и render, задержка preloadDelay, ручной вызов router.preloadRoute, восстановление прокрутки и MatchRoute. Для форм с несохранёнными изменениями предусмотрены useBlocker, Block и собственный интерфейс подтверждения. Перед использованием нужен router-core.
Скилл ставится отдельно для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. В Claude Code установка заканчивается появлением файла ~/.claude/skills/navigation/SKILL.md.
Какие задачи решает
- настроить типизированные ссылки с параметрами маршрута
- сделать переход после отправки формы
- добавить активное состояние пунктам навигации
- предзагружать маршрут по наведению или появлению в области просмотра
- заблокировать уход со страницы с несохранёнными изменениями
Примеры запросов агенту
- Настрой ссылку на
/posts/$postIdс параметромpostIdи активным состоянием. - Добавь предзагрузку маршрута по наведению и задержку
preloadDelayдля ссылки на пост. - Покажи, как заблокировать переход при изменённой форме через
useBlocker.
Как установить navigation
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a claude-code2Вручную: положить файлы
~/.claude/skills/navigation/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/navigation/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a codex2Вручную: положить файлы
.agents/skills/navigation/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a cursor2Вручную: положить файлы
.cursor/skills/navigation/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/navigation2Вручную: положить файлы
.github/skills/navigation/SKILL.md1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a gemini-cli2Командой платформы
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/navigationВручную: положить файлы
.devin/skills/navigation/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add TanStack/router --skill navigation -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о navigation
Как установить navigation в Claude Code?
Выполните npx skills add TanStack/router --skill navigation -a claude-code, затем используйте файл ~/.claude/skills/navigation/SKILL.md.
Что делает navigation?
Скилл объясняет навигацию TanStack Router: ссылки, программные переходы, относительные пути, активные состояния, предзагрузку и блокировку ухода со страницы.
Что нужно для работы navigation?
Скилл требует router-core. Для предзагрузки доступны стратегии intent, viewport и render.
Исходный текст
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