Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TanStack/router --skill navigation -a claude-code
Open on GitHub

What 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/$postId and pass its postId parameter.
  • Add intent-based preloading with preloadDelay to 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-code

2Manually: put the files in place

~/.claude/skills/navigation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/navigation/

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

Similar skills

All skills for Frontend and UI →

From the same set25

The whole set →
search-params search-params equips agents with TanStack Router search param patterns: schema validation, inheritance across child routes, and URL middlewares. CX Codex +1 228installs type-safety type-safety — a skill that teaches AI code generators to write type-safe TanStack Router code: never cast inferred values, register the module once, narrow types with from and getRouteApi, optimize TypeScript performance. CX Codex +1 223installs server-functions server-functions teaches your coding agent how to build type-safe RPCs in TanStack Start with createServerFn, validate inputs using Zod, and trigger mutations from UI components. CX Codex +1 221installs auth-and-guards auth-and-guards — a skill for protecting routes in TanStack Router. Redirects unauthenticated users, embeds role and permission checks, integrates Auth0, Clerk, Supabase via router context. CX Codex +1 219installs execution-model The execution-model skill teaches agents to separate server and browser code in TanStack Start, with SSR, hydration, imports, and environment variables in view. CX Codex +1 214installs code-splitting code-splitting — a skill for TanStack Router that splits route code into critical (config, loaders) and lazy (components). Automatically generates separate chunks per route, or manually control splitting with .lazy.tsx files. CX Codex +1 212installs not-found-and-errors not-found-and-errors teaches coding agents to configure 404 boundaries and error components in TanStack Router. It covers throwing notFound() and handling loader failures. CX Codex +1 211installs deployment deployment deploys TanStack Start to Cloudflare Workers, Netlify, Vercel, Node.js, Bun, and Railway. Controls SSR per route, static prerendering, and SEO config. CX Codex +1 210installs

Project sponsors

Companies that keep this analytics open