& {
defaultValue?: T
}
```
### inferParserType
TypeScript automatically infers the return type based on your parsers:
```ts theme={null}
const searchParamsCache = createSearchParamsCache({
count: parseAsInteger, // number | null
active: parseAsBoolean.withDefault(false), // boolean
tags: parseAsArrayOf(parseAsString) // string[] | null
})
const count = searchParamsCache.get('count') // number | null
const active = searchParamsCache.get('active') // boolean
const tags = searchParamsCache.get('tags') // string[] | null
const all = searchParamsCache.all()
// {
// count: number | null,
// active: boolean,
// tags: string[] | null
// }
```
## Examples
### Basic Usage
```tsx theme={null}
// searchParams.ts
import { createSearchParamsCache, parseAsString, parseAsInteger } from 'nuqs/server'
export const searchParamsCache = createSearchParamsCache({
q: parseAsString.withDefault(''),
page: parseAsInteger.withDefault(1),
category: parseAsString
})
// page.tsx
import { searchParamsCache } from './searchParams'
export default async function Page({ searchParams }) {
const { q } = await searchParamsCache.parse(searchParams)
return (
Search: {q}
{/* Can access cached params */}
)
}
// Results.tsx (nested server component)
import { searchParamsCache } from './searchParams'
export function Results() {
const page = searchParamsCache.get('page')
const category = searchParamsCache.get('category')
return Page {page} - Category: {category || 'All'}
}
```
### Next.js 15 Async searchParams
```tsx theme={null}
// Next.js 14 and earlier (synchronous)
export default function Page({ searchParams }) {
const { q } = searchParamsCache.parse(searchParams)
return Search: {q}
}
// Next.js 15+ (asynchronous)
export default async function Page({ searchParams }) {
const { q } = await searchParamsCache.parse(searchParams)
return Search: {q}
}
```
### Strict Mode
```tsx theme={null}
export default async function Page({ searchParams }) {
try {
// Throws if any parser fails
const params = await searchParamsCache.parse(searchParams, { strict: true })
} catch (error) {
console.error('Invalid search params:', error)
notFound()
}
}
```
### URL Keys Mapping
```tsx theme={null}
const searchParamsCache = createSearchParamsCache(
{
searchQuery: parseAsString,
pageNumber: parseAsInteger.withDefault(1)
},
{
urlKeys: {
searchQuery: 'q',
pageNumber: 'page'
}
}
)
// URL: ?q=laptop&page=2
// Access via internal names:
const searchQuery = searchParamsCache.get('searchQuery') // "laptop"
const pageNumber = searchParamsCache.get('pageNumber') // 2
```
### Using all()
```tsx theme={null}
import { searchParamsCache } from './searchParams'
export async function SearchResults() {
// Access all values at once
const { q, tags, sortBy } = searchParamsCache.all()
const results = await searchDatabase(q, tags, sortBy)
return (
{results.map(result => (
- {result.title}
))}
)
}
```
## Cache Lifecycle
The cache is scoped to a single page render using React's [`cache`](https://react.dev/reference/react/cache) function:
* **Created** when the page component renders
* **Shared** across all server components in the tree for that request
* **Cleared** after the request completes
* **Isolated** between different requests (no cross-request pollution)
```tsx theme={null}
// Each request gets its own cache instance
Request 1: ?q=foo&page=1 → Cache { q: 'foo', page: 1 }
Request 2: ?q=bar&page=2 → Cache { q: 'bar', page: 2 }
```
## Error Handling
The cache will throw an error if you try to access values before calling `parse()`:
```tsx theme={null}
// ❌ Will throw error
export default function Page({ searchParams }) {
// parse() not called yet!
const page = searchParamsCache.get('page')
// Error: [nuqs] Cannot access search params before calling parse()
}
// ✅ Correct usage
export default async function Page({ searchParams }) {
await searchParamsCache.parse(searchParams)
const page = searchParamsCache.get('page') // Works!
}
```
The cache will also throw if you call `parse()` multiple times with different inputs in the same request:
```tsx theme={null}
export default async function Page({ searchParams }) {
await searchParamsCache.parse(searchParams)
// ❌ Will throw error if searchParams changed
await searchParamsCache.parse(differentSearchParams)
// Error: Cannot call parse() with different inputs in the same request
}
```
If `parse()` is called multiple times with the **same** input (e.g., in both `generateMetadata` and the page component), the cached result is safely returned.
## Related
Learn how to use the cache in server components
One-off parsing with createLoader
Learn about available parser types