菜单
validateSearch, search param validation with Zod/Valibot/ArkType adapters, fallback(), search middlewares (retainSearchParams, stripSearchParams), custom serialization (parseSearch, stringifySearch), search param inheritance, loaderDeps for cache keys, reading and writing search params.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/mehdibha/dotUI --skill router-core-search-params命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Install TanStack Devtools, pick framework adapter (React/Vue/Solid/Preact), register plugins via plugins prop, configure shell (position, hotkeys, theme, hideUntilHover, requireUrlFlag, eventBusConfig). TanStackDevtools component, defaultOpen, localStorage persistence.
Configure @tanstack/devtools-vite for source inspection (data-tsd-source, inspectHotkey, ignore patterns), console piping (client-to-server, server-to-client, levels), enhanced logging, server event bus (port, host, HTTPS), production stripping (removeDevtoolsOnBuild), editor integration (launch-editor, custom editor.open). Must be FIRST plugin in Vite config. Vite ^6 || ^7 only.
React bindings for TanStack Start: createStart, StartClient, StartServer, React-specific imports, re-exports from @tanstack/react-router, full project setup with React, useServerFn hook.
基于 SOC 职业分类
正在显示 SKILL.md
| name | router-core/search-params |
| description | validateSearch, search param validation with Zod/Valibot/ArkType adapters, fallback(), search middlewares (retainSearchParams, stripSearchParams), custom serialization (parseSearch, stringifySearch), search param inheritance, loaderDeps for cache keys, reading and writing search params. |
| type | sub-skill |
| library | tanstack-router |
| library_version | 1.166.2 |
| requires | ["router-core"] |
| sources | ["TanStack/router:docs/router/guide/search-params.md","TanStack/router:docs/router/how-to/setup-basic-search-params.md","TanStack/router:docs/router/how-to/validate-search-params.md","TanStack/router:docs/router/how-to/navigate-with-search-params.md","TanStack/router:docs/router/how-to/share-search-params-across-routes.md","TanStack/router:docs/router/guide/custom-search-param-serialization.md"] |
TanStack Router treats search params as JSON-first application state. They are automatically parsed from the URL into structured objects (numbers, booleans, arrays, nested objects) and validated via validateSearch on each route.
CRITICAL: When using
zodValidator()and Zod v3, usefallback()from@tanstack/zod-adapter, NOT zod's.catch(). Using.catch()with the zod adapter makes the output typeunknown, destroying type safety. This does not apply to Valibot or ArkType (which use their own fallback mechanisms). It also does not apply to Zod v4, which should use.catch()and not use thezodValidator(). CRITICAL: Types are fully inferred. Never annotate the return ofuseSearch().
npm install zod @tanstack/zod-adapter
// src/routes/products.tsx
import { createFileRoute } from "@tanstack/react-router"
import { z } from "zod"
const productSearchSchema = z.object({
page: z.number().default(1).catch(1),
filter: z.string().default(""),
sort: z.enum(["newest", "oldest", "price"]).default("newest").catch("newest"),
})
export const = ()({
: productSearchSchema,
: ,
})
() {
{ page, filter, sort } = .()
(
)
}
Route.useSearch()function ProductsPage() {
const { page, sort } = Route.useSearch()
return <div>Page {page}</div>
}
getRouteApi()import { getRouteApi } from "@tanstack/react-router"
const routeApi = getRouteApi("/products")
function ProductFilters() {
const { sort } = routeApi.useSearch()
return <select value={sort}>{/* options */}</select>
}
useSearch({ from })import { useSearch } from "@tanstack/react-router"
function SortIndicator() {
const { sort } = useSearch({ from: "/products" })
return <span>Sorted by: {sort}</span>
}
useSearch({ strict: false })function GenericPaginator() {
const search = useSearch({ strict: false })
// search.page is number | undefined (union of all routes)
return <span>Page: {search.page ?? 1}</span>
}
import { Link } from "@tanstack/react-router"
function Pagination() {
return (
<Link
from="/products"
search={(prev) => ({ ...prev, page: prev.page + 1 })}
>
Next Page
</Link>
)
}
<Link to="/products" search={{ page: 1, filter: "", sort: "newest" }}>
Reset
</Link>
useNavigate()import { useNavigate } from "@tanstack/react-router"
function SortDropdown() {
const navigate = useNavigate({ from: "/products" })
return (
<select
onChange={(e) => {
navigate({
search: (prev) => ({ ...prev, sort: e.target.value, page: 1 }),
})
}}
>
<option value="newest">Newest</option>
<option value="price">Price</option>
</select>
)
}
Parent route search params are automatically merged into child routes:
// src/routes/shop.tsx — parent defines shared params
import { createFileRoute } from "@tanstack/react-router"
import { z } from "zod"
const shopSearchSchema = z.object({
currency: z.enum(["USD", "EUR"]).default("USD").catch("USD"),
})
export const Route = createFileRoute("/shop")({
validateSearch: shopSearchSchema,
})
// src/routes/shop/products.tsx — child inherits currency
import { createFileRoute } from "@tanstack/react-router"
export const Route = createFileRoute("/shop/products")({
component: ShopProducts,
})
function ShopProducts() {
// currency is available here from parent — fully typed
const { currency } = Route.useSearch()
return <div>Currency: {currency}</div>
}
retainSearchParams — Keep Params Across Navigationimport { createRootRoute, retainSearchParams } from "@tanstack/react-router"
import { z } from "zod"
const rootSearchSchema = z.object({
debug: z.boolean().optional(),
})
export const Route = createRootRoute({
validateSearch: rootSearchSchema,
search: {
middlewares: [retainSearchParams(["debug"])],
},
})
stripSearchParams — Remove Default Values from URLimport { createFileRoute, stripSearchParams } from "@tanstack/react-router"
import { z } from "zod"
const defaults = { sort: "newest", page: 1 }
const searchSchema = z.object({
sort: z.string().default(defaults.sort),
page: z.number().default(defaults.page),
})
export const Route = createFileRoute("/items")({
validateSearch: searchSchema,
search: {
middlewares: [stripSearchParams(defaults)],
},
})
export const Route = createFileRoute("/search")({
validateSearch: z.object({
retainMe: z.string().optional(),
arrayWithDefaults: z.string().array().default(["foo", "bar"]),
required: z.string(),
}),
search: {
middlewares: [
retainSearchParams(["retainMe"]),
stripSearchParams({ arrayWithDefaults: ["foo", "bar"] }),
],
},
})
Override the default JSON serialization at the router level:
import {
createRouter,
parseSearchWith,
stringifySearchWith,
} from "@tanstack/react-router"
const router = createRouter({
routeTree,
// Example: use JSURL2 for compact, human-readable URLs
parseSearch: parseSearchWith(parse),
stringifySearch: stringifySearchWith(stringify),
})
loaderDepsexport const Route = createFileRoute("/products")({
validateSearch: productSearchSchema,
// Pick ONLY the params the loader needs — not the entire search object
loaderDeps: ({ search }) => ({ page: search.page }),
loader: async ({ deps }) => {
return fetchProducts({ page: deps.page })
},
})
.catch() with zodValidator() instead of adapter fallback()// WRONG — .catch() with zodValidator makes the type unknown
const schema = z.object({ page: z.number().catch(1) })
validateSearch: zodValidator(schema) // page is typed as unknown!
// CORRECT — fallback() preserves the inferred type
import { fallback } from "@tanstack/zod-adapter"
const schema = z.object({ page: fallback(z.number(), 1) })
Important: This only applies when using Zod v3, not when using Zod v4. For v4, using .catch() is correct.
loaderDeps// WRONG — loader re-runs on ANY search param change
loaderDeps: ({ search }) => search
// CORRECT — loader only re-runs when page changes
loaderDeps: ({ search }) => ({ page: search.page })
// WRONG — Date does not serialize correctly to JSON in URLs
<Link search={{ startDate: new Date() }}>
// CORRECT — convert to ISO string
<Link search={{ startDate: new Date().toISOString() }}>
validateSearch blocks inheritance// WRONG — child cannot access shared params
export const Route = createRootRoute({
component: RootComponent,
// no validateSearch!
})
// CORRECT — parent must define validateSearch for children to inherit
export const Route = createRootRoute({
validateSearch: globalSearchSchema,
component: RootComponent,
})
// WRONG — replaces ALL search params, losing any existing ones
<Link to="." search={{ page: 2 }}>Page 2</Link>
// CORRECT — preserves existing params, updates only page
<Link to="." search={(prev) => ({ ...prev, page: 2 })}>Page 2</Link>