path-params — Claude Code skill: dynamic route segments
path-params — a skill for handling dynamic URL parameters in TanStack Router. Teaches agents to capture variable path segments, set up optional routes, and create patterns with prefixes and suffixes.
MIT 208 installs ★ 15,341 updated 2026-10-25
npx skills add TanStack/router --skill path-params -a claude-codeWhat path-params does
path-params unlocks URL parameter patterns in TanStack Router. The skill covers dynamic segments with $ prefix (e.g., /posts/$postId), splat routes ending in $ that expose the remainder as _splat, optional params in {-$paramName} format, and patterns like /posts/post-{$postId} or /files/{$fileName}.txt with fixed text around the variable.
You get hooks like useParams, methods params.parse and params.stringify, configuration of allowed characters via pathParamsAllowedCharacters, examples in loaders and beforeLoad, and navigation via Link and useNavigate by passing params as an object or function. A section covers i18n — optional locale segments such as /{-$locale}/about.
Param types fully infer automatically; no annotation of useParams() is needed. Critical rule: never interpolate params into the to string, always pass them via the params prop.
What it helps with
- Capture dynamic URL segments and bind them to route variables
- Build optional path sections that match whether or not they appear in the URL
- Create a catch-all route that captures the remainder of the path as a single variable
- Navigate between routes with parameters while preserving type safety
- Add multi-language support using optional locale in the path
Example prompts for the agent
- Create a route for a post with ID in the path and display the title using
useParams - Build an optional category segment at
/posts/{-$category}so both/postsand/posts/techwork - Navigate to
/posts/$postIdpassingparams={{ postId }}
How to install path-params
1Skills CLI (Vercel)
npx skills add TanStack/router --skill path-params -a claude-code2Manually: put the files in place
~/.claude/skills/path-params/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/path-params/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill path-params -a codex2Manually: put the files in place
.agents/skills/path-params/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill path-params -a cursor2Manually: put the files in place
.cursor/skills/path-params/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/path-params2Manually: put the files in place
.github/skills/path-params/SKILL.md1Skills CLI (Vercel)
npx skills add TanStack/router --skill path-params -a gemini-cli2Platform CLI
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/path-paramsManually: put the files in place
.devin/skills/path-params/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TanStack/router --skill path-params -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 path-params
How do I install path-params for Claude Code?
Run npx skills add TanStack/router --skill path-params -a claude-code, then add ~/.claude/skills/path-params/SKILL.md to the agent's context.
What does path-params do?
The skill teaches agents to work with dynamic route parameters in TanStack Router: capturing URL segments into variables, optional path sections, splat routes, prefix and suffix patterns, safe navigation, and proper type inference.
Why should I pass params as a prop instead of interpolating into to?
Interpolation loses type information and causes navigation errors. Always use the params prop separately from the route string to preserve safety and catch mistakes at build time.
Source text
SKILL.md · MIT
---
name: path-params
description: >-
Dynamic path segments ($paramName), splat routes ($ / _splat),
optional params ({-$paramName}), prefix/suffix patterns ({$param}.ext),
useParams, params.parse/stringify, pathParamsAllowedCharacters,
i18n locale patterns.
metadata:
type: sub-skill
library: tanstack-router
library_version: '1.171.15'
requires:
- router-core
sources:
- TanStack/router:docs/router/guide/path-params.md
- TanStack/router:docs/router/routing/routing-concepts.md
- TanStack/router:docs/router/guide/internationalization-i18n.md
---
# Path Params
Path params capture dynamic URL segments into named variables. They are defined with a `$` prefix in the route path.
> **CRITICAL**: Never interpolate params into the `to` string. Always use the `params` prop. This is the most common agent mistake for path params.
> **CRITICAL**: Types are fully inferred. Never annotate the return of `useParams()`.
## Dynamic Segments
A segment prefixed with `$` captures text until the next `/`.
```tsx
// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
// params.postId is string — fully inferred, do not annotate
return fetchPost(params.postId)
},
component: PostComponent,
})
function PostComponent() {
const { postId } = Route.useParams()
const data = Route.useLoaderData()
return (
<h1>
Post {postId}: {data.title}
</h1>
)
}
```
Multiple dynamic segments work across path levels:
```tsx
// src/routes/teams.$teamId.members.$memberId.tsx
export const Route = createFileRoute('/teams/$teamId/members/$memberId')({
component: MemberComponent,
})
function MemberComponent() {
const { teamId, memberId } = Route.useParams()
return (
<div>
Team {teamId}, Member {memberId}
</div>
)
}
```
## Splat / Catch-All Routes
A route with a path ending in `$` (bare dollar sign) captures everything after it. The value is available under the `_splat` key.
```tsx
// src/routes/files.$.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/files/$')({
component: FileViewer,
})
function FileViewer() {
const { _splat } = Route.useParams()
// URL: /files/documents/report.pdf → _splat = "documents/report.pdf"
return <div>File path: {_splat}</div>
}
```
## Optional Params
Optional params use `{-$paramName}` syntax. The segment may or may not be present. When absent, the value is `undefined`.
```tsx
// src/routes/posts.{-$category}.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/{-$category}')({
component: PostsComponent,
})
function PostsComponent() {
const { category } = Route.useParams()
// URL: /posts → category is undefined
// URL: /posts/tech → category is "tech"
return <div>{category ? `Posts in ${category}` : 'All Posts'}</div>
}
```
Multiple optional params:
```tsx
// Matches: /posts, /posts/tech, /posts/tech/hello-world
export const Route = createFileRoute('/posts/{-$category}/{-$slug}')({
component: PostComponent,
})
```
### i18n with Optional Locale
```tsx
// src/routes/{-$locale}/about.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/{-$locale}/about')({
component: AboutComponent,
})
function AboutComponent() {
const { locale } = Route.useParams()
const currentLocale = locale || 'en'
return <h1>{currentLocale === 'fr' ? 'À Propos' : 'About Us'}</h1>
}
// Matches: /about, /en/about, /fr/about
```
## Prefix and Suffix Patterns
Curly braces `{}` around `$paramName` allow text before or after the dynamic part within a single segment.
### Prefix
```tsx
// src/routes/posts/post-{$postId}.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/post-{$postId}')({
component: PostComponent,
})
function PostComponent() {
const { postId } = Route.useParams()
// URL: /posts/post-123 → postId = "123"
return <div>Post ID: {postId}</div>
}
```
### Suffix
```tsx
// src/routes/files/{$fileName}[.]txt.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/files/{$fileName}.txt')({
component: FileComponent,
})
function FileComponent() {
const { fileName } = Route.useParams()
// URL: /files/readme.txt → fileName = "readme"
return <div>File: {fileName}.txt</div>
}
```
### Combined Prefix + Suffix
```tsx
// URL: /users/user-456.json → userId = "456"
export const Route = createFileRoute('/users/user-{$userId}.json')({
component: UserComponent,
})
function UserComponent() {
const { userId } = Route.useParams()
return <div>User: {userId}</div>
}
```
## Navigating with Path Params
### Object Form
```tsx
import { Link } from '@tanstack/react-router'
function PostLink({ postId }: { postId: string }) {
return (
<Link to="/posts/$postId" params={{ postId }}>
View Post
</Link>
)
}
```
### Function Form (Preserves Other Params)
```tsx
function PostLink({ postId }: { postId: string }) {
return (
<Link to="/posts/$postId" params={(prev) => ({ ...prev, postId })}>
View Post
</Link>
)
}
```
### Programmatic Navigation
```tsx
import { useNavigate } from '@tanstack/react-router'
function GoToPost({ postId }: { postId: string }) {
const navigate = useNavigate()
return (
<button
onClick={() => {
navigate({ to: '/posts/$postId', params: { postId } })
}}
>
Go to Post
</button>
)
}
```
### Navigating with Optional Params
```tsx
// Include the optional param
<Link to="/posts/{-$category}" params={{ category: 'tech' }}>
Tech Posts
</Link>
// Omit the optional param (renders /posts)
<Link to="/posts/{-$category}" params={{ category: undefined }}>
All Posts
</Link>
```
## Reading Params Outside Route Components
### `useParams` with `from`
```tsx
import { useParams } from '@tanstack/react-router'
function PostHeader() {
const { postId } = useParams({ from: '/posts/$postId' })
return <h2>Post {postId}</h2>
}
```
### `useParams` with `strict: false`
```tsx
function GenericBreadcrumb() {
const params = useParams({ strict: false })
// params is a union of all possible route params
return <span>{params.postId ?? 'Home'}</span>
}
```
## Params in Loaders and `beforeLoad`
```tsx
export const Route = createFileRoute('/posts/$postId')({
beforeLoad: async ({ params }) => {
// params.postId available here
const canView = await checkPermission(params.postId)
if (!canView) throw redirect({ to: '/unauthorized' })
},
loader: async ({ params }) => {
return fetchPost(params.postId)
},
})
```
## Allowed Characters
By default, params are encoded with `encodeURIComponent`. Allow extra characters via router config:
```tsx
import { createRouter } from '@tanstack/react-router'
const router = createRouter({
routeTree,
pathParamsAllowedCharacters: ['@', '+'],
})
```
Allowed characters: `;`, `:`, `@`, `&`, `=`, `+`, `$`, `,`.
## Common Mistakes
### 1. CRITICAL (cross-skill): Interpolating path params into `to` string
```tsx
// WRONG — breaks type safety and param encoding
<Link to={`/posts/${postId}`}>Post</Link>
// CORRECT — use params prop
<Link to="/posts/$postId" params={{ postId }}>Post</Link>
```
### 2. MEDIUM: Using `*` for splat routes instead of `$`
TanStack Router uses `$` for splat routes. The captured value is under `_splat`, not `*`.
```tsx
// WRONG (React Router / other frameworks)
// <Route path="/files/*" />
// CORRECT (TanStack Router)
// File: src/routes/files.$.tsx
export const Route = createFileRoute('/files/$')({
component: () => {
const { _splat } = Route.useParams()
return <div>{_splat}</div>
},
})
```
> Note: `*` works in v1 for backwards compatibility but will be removed in v2. Always use `_splat`.
### 3. MEDIUM: Using curly braces for basic dynamic segments
Curly braces are ONLY for prefix/suffix patterns and optional params. Basic dynamic segments use bare `$`.
```tsx
// WRONG — braces not needed for basic params
createFileRoute('/posts/{$postId}')
// CORRECT — bare $ for basic dynamic segments
createFileRoute('/posts/$postId')
// CORRECT — braces for prefix pattern
createFileRoute('/posts/post-{$postId}')
// CORRECT — braces for optional param
createFileRoute('/posts/{-$category}')
```
### 4. Params are always strings
Path params are always parsed as strings. If you need a number, parse in the loader or component:
```tsx
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const id = parseInt(params.postId, 10)
if (isNaN(id)) throw notFound()
return fetchPost(id)
},
})
```
You can also use `params.parse` and `params.stringify` on the route for bidirectional transformation:
```tsx
export const Route = createFileRoute('/posts/$postId')({
params: {
parse: (raw) => ({ postId: parseInt(raw.postId, 10) }),
stringify: (parsed) => ({ postId: String(parsed.postId) }),
},
loader: async ({ params }) => {
// params.postId is now number
return fetchPost(params.postId)
},
})
```
© TanStack · MIT · TanStack/router