|
| 1 | +--- |
| 2 | +title: Share Search Parameters Across Routes |
| 3 | +--- |
| 4 | + |
| 5 | +# How to Share Search Parameters Across Routes |
| 6 | + |
| 7 | +Search parameters automatically inherit from parent routes in TanStack Router. When a parent route validates search parameters, child routes can access them via `Route.useSearch()` alongside their own parameters. |
| 8 | + |
| 9 | +## How Parameter Inheritance Works |
| 10 | + |
| 11 | +TanStack Router automatically merges search parameters from parent routes with child route parameters. This happens through the route hierarchy: |
| 12 | + |
| 13 | +1. **Parent route** validates shared parameters with `validateSearch` |
| 14 | +2. **Child routes** automatically inherit those validated parameters |
| 15 | +3. **`Route.useSearch()`** returns both local and inherited parameters |
| 16 | + |
| 17 | +## Global Parameters via Root Route |
| 18 | + |
| 19 | +Share parameters across your entire application by validating them in the root route: |
| 20 | + |
| 21 | +```tsx |
| 22 | +// routes/__root.tsx |
| 23 | +import { createRootRoute, Outlet } from '@tanstack/react-router' |
| 24 | +import { zodValidator } from '@tanstack/zod-adapter' |
| 25 | +import { z } from 'zod' |
| 26 | + |
| 27 | +const globalSearchSchema = z.object({ |
| 28 | + theme: z.enum(['light', 'dark']).default('light'), |
| 29 | + lang: z.enum(['en', 'es', 'fr']).default('en'), |
| 30 | + debug: z.boolean().default(false), |
| 31 | +}) |
| 32 | + |
| 33 | +export const Route = createRootRoute({ |
| 34 | + validateSearch: zodValidator(globalSearchSchema), |
| 35 | + component: RootComponent, |
| 36 | +}) |
| 37 | + |
| 38 | +function RootComponent() { |
| 39 | + const { theme, lang, debug } = Route.useSearch() |
| 40 | + |
| 41 | + return ( |
| 42 | + <div className={`app theme-${theme} lang-${lang}`}> |
| 43 | + {debug && <DebugPanel />} |
| 44 | + <Outlet /> |
| 45 | + </div> |
| 46 | + ) |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +```tsx |
| 51 | +// routes/products/index.tsx |
| 52 | +import { createFileRoute } from '@tanstack/react-router' |
| 53 | +import { zodValidator } from '@tanstack/zod-adapter' |
| 54 | +import { z } from 'zod' |
| 55 | + |
| 56 | +const productSearchSchema = z.object({ |
| 57 | + page: z.number().default(1), |
| 58 | + category: z.string().default('all'), |
| 59 | +}) |
| 60 | + |
| 61 | +export const Route = createFileRoute('/products/')({ |
| 62 | + validateSearch: zodValidator(productSearchSchema), |
| 63 | + component: ProductsPage, |
| 64 | +}) |
| 65 | + |
| 66 | +function ProductsPage() { |
| 67 | + // Contains both local (page, category) AND inherited (theme, lang, debug) parameters |
| 68 | + const search = Route.useSearch() |
| 69 | + |
| 70 | + return ( |
| 71 | + <div> |
| 72 | + <h1>Products (Theme: {search.theme})</h1> |
| 73 | + <p>Page: {search.page}</p> |
| 74 | + <p>Category: {search.category}</p> |
| 75 | + </div> |
| 76 | + ) |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +## Section-Specific Parameters via Layout Routes |
| 81 | + |
| 82 | +Share parameters within a section of your app using layout routes: |
| 83 | + |
| 84 | +```tsx |
| 85 | +// routes/_authenticated.tsx |
| 86 | +import { createFileRoute, Outlet } from '@tanstack/react-router' |
| 87 | +import { zodValidator } from '@tanstack/zod-adapter' |
| 88 | +import { z } from 'zod' |
| 89 | + |
| 90 | +const authSearchSchema = z.object({ |
| 91 | + impersonate: z.string().optional(), |
| 92 | + sidebar: z.boolean().default(true), |
| 93 | + notifications: z.boolean().default(true), |
| 94 | +}) |
| 95 | + |
| 96 | +export const Route = createFileRoute('/_authenticated')({ |
| 97 | + validateSearch: zodValidator(authSearchSchema), |
| 98 | + component: AuthenticatedLayout, |
| 99 | +}) |
| 100 | + |
| 101 | +function AuthenticatedLayout() { |
| 102 | + const search = Route.useSearch() |
| 103 | + |
| 104 | + return ( |
| 105 | + <div className="authenticated-layout"> |
| 106 | + {search.sidebar && <Sidebar />} |
| 107 | + <main className="main-content"> |
| 108 | + {search.notifications && <NotificationBar />} |
| 109 | + <Outlet /> |
| 110 | + </main> |
| 111 | + {search.impersonate && ( |
| 112 | + <ImpersonationBanner user={search.impersonate} /> |
| 113 | + )} |
| 114 | + </div> |
| 115 | + ) |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +```tsx |
| 120 | +// routes/_authenticated/dashboard.tsx |
| 121 | +import { createFileRoute } from '@tanstack/react-router' |
| 122 | + |
| 123 | +export const Route = createFileRoute('/_authenticated/dashboard')({ |
| 124 | + component: DashboardPage, |
| 125 | +}) |
| 126 | + |
| 127 | +function DashboardPage() { |
| 128 | + // Contains inherited auth parameters (impersonate, sidebar, notifications) |
| 129 | + const search = Route.useSearch() |
| 130 | + |
| 131 | + return ( |
| 132 | + <div> |
| 133 | + <h1>Dashboard</h1> |
| 134 | + {search.impersonate && ( |
| 135 | + <Alert>Currently impersonating: {search.impersonate}</Alert> |
| 136 | + )} |
| 137 | + <DashboardContent /> |
| 138 | + </div> |
| 139 | + ) |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +## Common Use Cases |
| 144 | + |
| 145 | +**Global Application Settings:** |
| 146 | +- Theme, language, timezone |
| 147 | +- Debug flags, feature toggles |
| 148 | +- Analytics tracking (UTM parameters) |
| 149 | + |
| 150 | +**Section-Specific State:** |
| 151 | +- Authentication context (user role, impersonation) |
| 152 | +- Layout preferences (sidebar, density) |
| 153 | +- Workspace or organization context |
| 154 | + |
| 155 | +**Persistent UI State:** |
| 156 | +- Modal visibility, drawer state |
| 157 | +- Filter presets, view modes |
| 158 | +- Accessibility preferences |
| 159 | + |
| 160 | +## Common Problems |
| 161 | + |
| 162 | +### Problem: Parameters Not Inheriting |
| 163 | + |
| 164 | +**Cause**: Parent route not validating the shared parameters. |
| 165 | + |
| 166 | +```tsx |
| 167 | +// ❌ Root route missing validateSearch |
| 168 | +export const Route = createRootRoute({ |
| 169 | + component: RootComponent, // No validateSearch |
| 170 | +}) |
| 171 | + |
| 172 | +// Child route can't access theme parameter |
| 173 | +function ProductsPage() { |
| 174 | + const search = Route.useSearch() // No theme available |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +**Solution**: Add `validateSearch` to the parent route: |
| 179 | + |
| 180 | +```tsx |
| 181 | +// ✅ Root route validates shared parameters |
| 182 | +export const Route = createRootRoute({ |
| 183 | + validateSearch: zodValidator(globalSearchSchema), |
| 184 | + component: RootComponent, |
| 185 | +}) |
| 186 | +``` |
| 187 | + |
| 188 | +### Problem: Navigation Loses Shared Parameters |
| 189 | + |
| 190 | +**Cause**: Not preserving inherited parameters during navigation. |
| 191 | + |
| 192 | +```tsx |
| 193 | +// ❌ Navigation overwrites all search parameters |
| 194 | +router.navigate({ |
| 195 | + to: '/products', |
| 196 | + search: { page: 1 }, // Loses theme, lang, etc. |
| 197 | +}) |
| 198 | +``` |
| 199 | + |
| 200 | +**Solution**: Preserve existing parameters with function syntax: |
| 201 | + |
| 202 | +```tsx |
| 203 | +// ✅ Preserve existing parameters |
| 204 | +router.navigate({ |
| 205 | + to: '/products', |
| 206 | + search: (prev) => ({ ...prev, page: 1 }), |
| 207 | +}) |
| 208 | +``` |
| 209 | + |
| 210 | +### Problem: Type Errors with Inherited Parameters |
| 211 | + |
| 212 | +**Cause**: Child route schema doesn't account for inherited parameters. |
| 213 | + |
| 214 | +```tsx |
| 215 | +// ❌ TypeScript error: Property 'theme' doesn't exist |
| 216 | +const search = Route.useSearch() |
| 217 | +console.log(search.theme) // Type error |
| 218 | +``` |
| 219 | + |
| 220 | +**Solution**: TypeScript automatically infers inherited types when using `validateSearch`. No additional typing needed - the inheritance works automatically. |
| 221 | + |
| 222 | +## Production Checklist |
| 223 | + |
| 224 | +- [ ] **Clear ownership**: Document which route validates which shared parameters |
| 225 | +- [ ] **Avoid conflicts**: Use distinct parameter names across route levels |
| 226 | +- [ ] **Preserve on navigation**: Use function syntax to maintain inherited parameters |
| 227 | +- [ ] **Minimal URLs**: Only include essential shared parameters |
| 228 | +- [ ] **Graceful defaults**: Provide fallback values for all shared parameters |
| 229 | + |
| 230 | +<!-- |
| 231 | +## Common Next Steps |
| 232 | +
|
| 233 | +After implementing shared search parameters, you might want to: |
| 234 | +
|
| 235 | +- [Build Advanced Search Parameter Middleware](./advanced-search-param-middleware.md) - Create reusable parameter sharing logic |
| 236 | +- [Handle Search Parameters in Forms](./search-params-in-forms.md) - Integrate shared parameters with form state |
| 237 | +- [Debug Search Parameter Issues](./debug-search-param-issues.md) - Troubleshoot parameter sharing problems |
| 238 | +--> |
| 239 | + |
| 240 | +## Related Resources |
| 241 | + |
| 242 | +- [Set Up Basic Search Parameters](./setup-basic-search-params.md) - Learn search parameter fundamentals |
| 243 | +- [Navigate with Search Parameters](./navigate-with-search-params.md) - Navigate while preserving search state |
| 244 | +- [Validate Search Parameters with Schemas](./validate-search-params.md) - Add type safety to shared parameters |
0 commit comments