nuqs

https://nuqs.dev/docs
Admin
nuqs is a library for managing URL query states in React applications, supporting various frameworks...
Tokens:22,587
Snippets:261
Trust Score:6.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install nuqs package

Source: https://nuqs.dev/docs

Use the following command to install the nuqs package via your preferred package manager.

```bash
npm i nuqs
```

--------------------------------

### Install nuqs package

Source: https://nuqs.dev/docs/installation

Commands to install the nuqs package using common JavaScript package managers.

```bash
npm install nuqs
```

```bash
pnpm add nuqs
```

```bash
yarn add nuqs
```

```bash
bun add nuqs
```

--------------------------------

### Initialize withNuqsTestingAdapter

Source: https://nuqs.dev/docs/testing

Examples of passing different searchParams formats to the testing adapter.

```tsx
withNuqsTestingAdapter({
  searchParams: '?q=hello&limit=10'
})

withNuqsTestingAdapter({
  searchParams: new URLSearchParams('?q=hello&limit=10')
})

withNuqsTestingAdapter({
  searchParams: {
    q: 'hello',
    limit: '10' // Values are serialized strings
  }
})
```

--------------------------------

### Usage example with Effect Schema

Source: https://nuqs.dev/docs/parsers/community/effect-schema

Demonstrates defining a schema class and composing it with base64/JSON transformations to create a query state parser.

```ts
import { Schema } from 'effect'

class User extends Schema.Class<User>('User')({
  name: Schema.String,
  age: Schema.Positive
}) {}

const ToBase64UrlEncodedJson = Schema.compose(Schema.StringFromBase64Url, Schema.parseJson())
const schema = Schema.compose(ToBase64UrlEncodedJson, User)

const parser = createSchemaParser(schema).withDefault(new User({ name: 'John Vim', age: 25 }))

const [user, setUser] = useQueryState('user', parser)
```

--------------------------------

### Server-side error message

Source: https://nuqs.dev/docs/migrations/v2

Example of the error encountered when calling client-side functions from the server.

```txt
Error: Attempted to call withDefault() from the server but withDefault is on
the client. It's not possible to invoke a client function from the server, it can
only be rendered as a Component or passed to props of a Client
Component.
```

--------------------------------

### Test components with Vitest

Source: https://nuqs.dev/docs/testing

Use the testing adapter to mock URL updates and verify state changes in components using nuqs.

```tsx
// [!code word:withNuqsTestingAdapter]
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { withNuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'

it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>()
  render(<CounterButton />, {
    // 1. Setup the test by passing initial search params / querystring:
    wrapper: withNuqsTestingAdapter({ searchParams: '?count=42', onUrlUpdate })
  })
  // 2. Act
  const button = screen.getByRole('button')
  await user.click(button)
  // 3. Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent('count is 43')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  const event = onUrlUpdate.mock.calls[0]![0]!
  expect(event.queryString).toBe('?count=43')
  expect(event.searchParams.get('count')).toBe('43')
  expect(event.options.history).toBe('push')
})
```

```tsx
// [!code word:withNuqsTestingAdapter]
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { withNuqsTestingAdapter, type OnUrlUpdateFunction } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'

it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
  render(<CounterButton />, {
    // 1. Setup the test by passing initial search params / querystring:
    wrapper: withNuqsTestingAdapter({ searchParams: '?count=42', onUrlUpdate })
  })
  // 2. Act
  const button = screen.getByRole('button')
  await user.click(button)
  // 3. Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent('count is 43')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  const event = onUrlUpdate.mock.calls[0]![0]!
  expect(event.queryString).toBe('?count=43')
  expect(event.searchParams.get('count')).toBe('43')
  expect(event.options.history).toBe('push')
})
```

--------------------------------

### Configure startTransition and shallow routing

Source: https://nuqs.dev/docs/migrations/v2

Explicitly set shallow: false when using startTransition to maintain server updates and loading states.

```diff
useQueryState('q', {
  startTransition: true,
+ shallow: false
})
```

--------------------------------

### Enable transitions with useQueryState

Source: https://nuqs.dev/docs/options

Integrate React's useTransition hook by passing the startTransition function to the withOptions method. Requires shallow: false to be explicitly set in nuqs v2.0.0 and later.

```tsx
'use client'

import React from 'react'
import { useQueryState, parseAsString } from 'nuqs'

function ClientComponent({ data }) {
  // 1. Provide your own useTransition hook:
  // [!code word:startTransition:1]
  const [isLoading, startTransition] = React.useTransition()
  const [query, setQuery] = useQueryState(
    'query',
    // 2. Pass the `startTransition` as an option:
    // [!code word:startTransition:1]
    parseAsString.withOptions({ startTransition, shallow: false })
  )
  // 3. `isLoading` will be true while the server is re-rendering
  // and streaming RSC payloads, when the query is updated via `setQuery`.

  // Indicate loading state
  if (isLoading) return <div>Loading...</div>

  // Normal rendering with data
  return <div>...</div>
}
```

--------------------------------

### Enable browser debug logs

Source: https://nuqs.dev/docs/debugging

Import the debug entry point once in your application to enable logging.

```ts
// Once in your app:
import 'nuqs/debug'
```

--------------------------------

### Configure global default options for NuqsAdapter

Source: https://nuqs.dev/docs/options

Sets default behaviors for history, shallow routing, scrolling, and URL update throttling across the application.

```tsx
// [!code word:defaultOptions]
<NuqsAdapter
  defaultOptions={{
    history: 'push',
    shallow: false,
    scroll: true,
    clearOnDefault: false,
    limitUrlUpdates: throttle(250),
  }}
>
  {children}
</NuqsAdapter>
```

--------------------------------

### useQueryStates(parsers, options)

Source: https://nuqs.dev/docs/batching

Initializes a hook to manage multiple query parameters as an object. The hook returns the current state object and a setter function to update one or more keys at once.

```APIDOC
## useQueryStates(parsers, options)

### Description
Manages multiple URL search parameters as a single state object. Updates are batched to minimize URL changes.

### Parameters
- **parsers** (Object) - Required - An object mapping state keys to their respective parsers (e.g., parseAsFloat).
- **options** (Object) - Optional - Configuration options including `history` ('push' or 'replace') and `urlKeys` for mapping internal variable names to URL-friendly keys.

### Usage Example
```ts
const [coordinates, setCoordinates] = useQueryStates(
  {
    lat: parseAsFloat.withDefault(45.18),
    lng: parseAsFloat.withDefault(5.72)
  },
  {
    history: 'push'
  }
)
```

### Setter Function
- **setCoordinates(values, options)** - Updates the URL search parameters. Passing `null` clears all keys managed by the hook.
- **options** (Object) - Optional - Call-level options such as `{ shallow: false }`.
```

--------------------------------

### Enable server debug logs

Source: https://nuqs.dev/docs/debugging

Set the DEBUG environment variable to include 'nuqs' to enable server-side logging.

```bash
DEBUG=nuqs node server.js
```

```bash
DEBUG=nuqs pnpm dev
```

--------------------------------

### Import ISO 8601 Datetime Parser

Source: https://nuqs.dev/docs/parsers

Import the ISO 8601 datetime parser from the nuqs library.

```typescript
import { parseAsIsoDateTime } from 'nuqs'
```

--------------------------------

### Defining default values for query state

Source: https://nuqs.dev/docs/basic-usage

Demonstrates how to provide default values using the options object or the .withDefault builder method on parsers.

```ts
const [search] = useQueryState('search', { defaultValue: '' })
//      ^? string

const [count] = useQueryState('count', parseAsInteger)
//      ^? number | null -> no default value = nullable

const [count] = useQueryState('count', parseAsInteger.withDefault(0))
//      ^? number
```

--------------------------------

### Wrapping client components in a Suspense boundary

Source: https://nuqs.dev/docs/troubleshooting

Use the 'use client' directive and wrap components using useQueryState in a Suspense boundary to resolve Next.js search parameter errors.

```tsx
'use client'

export default function Page() {
  return (
    <Suspense>
      <Client />
    </Suspense>
  )
}

function Client() {
  const [foo, setFoo] = useQueryState('foo')
  // ...
}
```

--------------------------------

### Configure NuqsAdapter in Remix

Source: https://nuqs.dev/docs/adapters

Wrap the root component with the Remix-specific NuqsAdapter to support query state management in Remix applications.

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/remix'

// ...

export default function App() {
  return (
    <NuqsAdapter>
      <Outlet />
    </NuqsAdapter>
  )
}
```

--------------------------------

### Configure options at the hook level

Source: https://nuqs.dev/docs/options

Use the builder pattern to pass options like history management when initializing the hook.

```ts
// [!code word:withOptions]
const [state, setState] = useQueryState(
  'foo',
  parseAsString.withOptions({ history: 'push' })
)
```

--------------------------------

### Check nuqs version

Source: https://nuqs.dev/docs

Displays the current version of the nuqs package.

```text
nuqs@2.9.5
```

--------------------------------

### Test Components with NuqsTestingAdapter

Source: https://nuqs.dev/docs/migrations/v2

Use the testing adapter to mock URL state and verify updates in unit tests without relying on router internals.

```tsx
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { NuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'

it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>()
  render(<CounterButton />, {
    // Setup the test by passing initial search params / querystring:
    wrapper: ({ children }) => (
      <NuqsTestingAdapter searchParams="?count=1" onUrlUpdate={onUrlUpdate}>
        {children}
      </NuqsTestingAdapter>
    )
  })
  // Act
  const button = screen.getByRole('button')
  await user.click(button)
  // Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent('count is 2')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  expect(onUrlUpdate.mock.calls[0][0].queryString).toBe('?count=2')
  expect(onUrlUpdate.mock.calls[0][0].searchParams.get('count')).toBe('2')
  expect(onUrlUpdate.mock.calls[0][0].options.history).toBe('push')
})
```

--------------------------------

### Import Date Parsers

Source: https://nuqs.dev/docs/parsers/built-in

Import specific parsers for ISO 8601 datetime, ISO 8601 date, and Unix timestamps.

```ts
import { parseAsIsoDateTime } from 'nuqs'
```

```ts
import { parseAsIsoDate } from 'nuqs'
```

```ts
import { parseAsTimestamp } from 'nuqs'
```

--------------------------------

### Server-side Parser Imports

Source: https://nuqs.dev/docs/parsers

Guidelines for importing parsers in environments that require compatibility with both server and client code.

```APIDOC
## Server-side Parser Imports

### Description
For shared code in Next.js app router environments, import parsers from `nuqs/server` to avoid `'use client'` directive issues.

### Usage
```typescript
import { parseAsString } from 'nuqs/server'
```

### Notes
- Importing from `nuqs` directly in shared code may cause bundling errors when using methods like `.withDefault` or `.withOptions`.
```

--------------------------------

### useQueryState Options

Source: https://nuqs.dev/docs/options

Configuration options for controlling scroll behavior and URL update frequency in useQueryState.

```APIDOC
## useQueryState Options

### Description
Configures the behavior of the `useQueryState` hook, including page scrolling and URL update throttling or debouncing.

### Parameters
- **scroll** (boolean) - Optional - Whether to scroll to the top of the page on navigation updates. Defaults to false.
- **limitUrlUpdates** (object) - Optional - Configuration for rate-limiting URL updates.
  - **method** (string) - 'throttle' or 'debounce'.
  - **timeMs** (number) - The time in milliseconds for the rate limit. Values below 50ms are ignored.

### Usage Example
```ts
useQueryState('foo', {
  scroll: true,
  limitUrlUpdates: {
    method: 'throttle',
    timeMs: 1000
  }
})
```
```

--------------------------------

### NuqsAdapter defaultOptions

Source: https://nuqs.dev/docs/options

Configures global default values for search parameter behavior across the application.

```APIDOC
## <NuqsAdapter> defaultOptions

### Description
Sets global default values for search parameter updates. These defaults apply to the entire children tree of the adapter.

### Properties
- **history** (string) - Optional - Navigation history behavior ('push' or 'replace').
- **shallow** (boolean) - Optional - Whether to perform shallow routing.
- **scroll** (boolean) - Optional - Whether to scroll to the top after update.
- **clearOnDefault** (boolean) - Optional - Whether to remove search params when they match the default value.
- **limitUrlUpdates** (function) - Optional - Throttling or debouncing function for URL updates.
```

--------------------------------

### Configure NuqsAdapter for Next.js App Router

Source: https://nuqs.dev/docs/migrations/v2

Wrap the root layout with NuqsAdapter to enable type-safe URL state in Next.js App Router.

```tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'

export default function RootLayout({
  children
}: {
  children: ReactNode
}) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}
```

--------------------------------

### Use cache in Page and Server/Client components

Source: https://nuqs.dev/docs/server-side

Initialize the cache in the Page component and consume it in nested Server and Client components.

```tsx
import { coordinatesCache } from './searchParams'
import { Server } from './server'
import { Client } from './client'

export default async function Page({ searchParams }) {
  // Note: you can also use strict mode here:
  await coordinatesCache.parse(searchParams, { strict: true })
  return (
    <>
      <Server />
      <Suspense>
        <Client />
      </Suspense>
    </>
  )
}
```

```tsx
import { coordinatesCache } from './searchParams'

export function Server() {
  const { lat, lng } = coordinatesCache.all()
  // or access keys individually:
  const lat = coordinatesCache.get('lat')
  const lng = coordinatesCache.get('lng')
  return (
    <span>
      Latitude: {lat} - Longitude: {lng}
    </span>
  )
}
```

```tsx
'use client'

import { useQueryStates } from 'nuqs'
import { coordinatesParsers } from './searchParams'

export function Client() {
  const [{ lat, lng }, setCoordinates] = useQueryStates(coordinatesParsers)
  // ...
}
```

--------------------------------

### Using useQueryStates for grouped keys

Source: https://nuqs.dev/docs/batching

Manage multiple related query keys as a single object with defined parsers.

```ts
import { useQueryStates, parseAsFloat } from 'nuqs'

const [coordinates, setCoordinates] = useQueryStates(
  {
    lat: parseAsFloat.withDefault(45.18),
    lng: parseAsFloat.withDefault(5.72)
  },
  {
    history: 'push'
  }
)

const { lat, lng } = coordinates

// Set all (or a subset of) the keys in one go:
const search = await setCoordinates({
  lat: Math.random() * 180 - 90,
  lng: Math.random() * 360 - 180
})
```

--------------------------------

### Create a search params loader

Source: https://nuqs.dev/docs/server-side

Define a search parameter descriptor object and initialize a loader function using createLoader.

```tsx
import { parseAsFloat, createLoader } from 'nuqs/server'

// Describe your search params, and reuse this in useQueryStates / createSerializer:
export const coordinatesSearchParams = {
  latitude: parseAsFloat.withDefault(0),
  longitude: parseAsFloat.withDefault(0)
}

export const loadSearchParams = createLoader(coordinatesSearchParams)
```

--------------------------------

### Configuring search params with default values and options

Source: https://nuqs.dev/docs/parsers/built-in

Use the builder pattern to specify default values and options for search parameters.

```ts
export const searchParamsParsers = {
  q: parseAsString.withDefault('').withOptions({
    shallow: false
  })
}
```

--------------------------------

### Configure shorter URL keys

Source: https://nuqs.dev/docs/server-side

Map internal variable names to shorter keys in the URL using the urlKeys configuration.

```ts
export const coordinatesParsers = {
  // Use human-readable variable names throughout your codebase
  latitude: parseAsFloat.withDefault(45.18),
  longitude: parseAsFloat.withDefault(5.72)
}
export const coordinatesCache = createSearchParamsCache(coordinatesParsers, {
  urlKeys: {
    // Remap them to read from shorter keys in the URL
    latitude: 'lat',
    longitude: 'lng'
  }
})
```

--------------------------------

### Import Timestamp Parser

Source: https://nuqs.dev/docs/parsers

Import the Unix epoch millisecond timestamp parser.

```typescript
import { parseAsTimestamp } from 'nuqs'
```

--------------------------------

### Configure NuqsAdapter in React SPA

Source: https://nuqs.dev/docs/adapters

Wrap the root component with NuqsAdapter to enable query state management in a Vite-based React SPA.

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(document.getElementById('root')!).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>
)
```

--------------------------------

### Import parsers for server-side usage

Source: https://nuqs.dev/docs/parsers/built-in

Import from nuqs/server to avoid bundling errors in Next.js app router shared code.

```ts
import { parseAsString } from 'nuqs/server'
```

--------------------------------

### Update import path for parsers

Source: https://nuqs.dev/docs/migrations/v2

Replace the deprecated nuqs/parsers import path with nuqs/server to accommodate server-side utilities.

```diff
- import { parseAsInteger, createSearchParamsCache } from 'nuqs/parsers'
+ import { parseAsInteger, createSearchParamsCache } from 'nuqs/server'
```

--------------------------------

### Use Index Parser

Source: https://nuqs.dev/docs/parsers

Handle zero-indexed pagination by applying a +1 offset to the serialized string.

```typescript
import { parseAsIndex } from 'nuqs'

const [pageIndex] = useQueryState('page', parseAsIndex.withDefault(0))
```

```typescript
pageIndex: 0 // internal state is zero-indexed
```

--------------------------------

### Test hooks with React Testing Library

Source: https://nuqs.dev/docs/testing

Use withNuqsTestingAdapter as a wrapper in renderHook to provide initial search parameters for testing hooks.

```tsx
import { withNuqsTestingAdapter } from 'nuqs/adapters/testing'

const { result } = renderHook(() => useTheHookToTest(), {
  wrapper: withNuqsTestingAdapter({
    searchParams: { count: "42" },
  }),
})
```

--------------------------------

### Update test command for ESM

Source: https://nuqs.dev/docs/testing

Include the --experimental-vm-modules flag in your package.json test script.

```json
// [!code word:--experimental-vm-modules]
{
  "scripts": {
    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"
  }
}
```

--------------------------------

### Import Unified Next.js Adapter

Source: https://nuqs.dev/docs/migrations/v2

Use the unified adapter when an application utilizes both App and Pages routers.

```tsx
import { NuqsAdapter } from 'nuqs/adapters/next'
```

--------------------------------

### Configure NuqsAdapter for TanStack Router

Source: https://nuqs.dev/docs/adapters

Wrap the root route component with NuqsAdapter to integrate Nuqs with TanStack Router.

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/tanstack-router'
import { Outlet, createRootRoute } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: () => (
    <>
      <NuqsAdapter>
        <Outlet />
      </NuqsAdapter>
    </>
  ),
})
```

--------------------------------

### Configure NuqsAdapter for Next.js Pages Router

Source: https://nuqs.dev/docs/migrations/v2

Wrap the custom App component with NuqsAdapter for applications using the Pages router.

```tsx
import type { AppProps } from 'next/app'
import { NuqsAdapter } from 'nuqs/adapters/next/pages'

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <NuqsAdapter>
      <Component {...pageProps} />
    </NuqsAdapter>
  )
}
```

--------------------------------

### Importing the string parser

Source: https://nuqs.dev/docs/parsers/built-in

Import the parseAsString function to handle string search parameters.

```ts
import { parseAsString } from 'nuqs'
```

--------------------------------

### NuqsTestingAdapter

Source: https://nuqs.dev/docs/testing

A wrapper component used to provide a testing context for components that utilize nuqs hooks.

```APIDOC
## NuqsTestingAdapter

### Description
A wrapper component that provides the necessary context for components using nuqs hooks during testing.

### Usage
```tsx
import { NuqsTestingAdapter } from 'nuqs/adapters/testing'

<NuqsTestingAdapter>
  <ComponentsUsingNuqs/>
</NuqsTestingAdapter>
```
```

--------------------------------

### Apply string refinements to Zod codecs

Source: https://nuqs.dev/docs/parsers/community/zod-codecs

Demonstrates applying Zod string refinements to the input type of a codec to validate URL parameters.

```ts
z.codec(z.uuid(), ...)
z.codec(z.email(), ...)
z.codec(z.base64url(), ...)
```

--------------------------------

### Configure NuqsAdapter for React Router

Source: https://nuqs.dev/docs/adapters

Wrap the application root with NuqsAdapter to enable Nuqs functionality in React Router applications.

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/react-router/v7'
import { Outlet } from 'react-router'

// ...

export default function App() {
  return (
    <NuqsAdapter>
      <Outlet />
    </NuqsAdapter>
  )
}
```

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/react-router/v8'
import { Outlet } from 'react-router'

// ...

export default function App() {
  return (
    <NuqsAdapter>
      <Outlet />
    </NuqsAdapter>
  )
}
```

--------------------------------

### Import ISO 8601 Date Parser

Source: https://nuqs.dev/docs/parsers

Import the ISO 8601 date parser, available since version 2.1.0.

```typescript
import { parseAsIsoDate } from 'nuqs'
```

--------------------------------

### withNuqsTestingAdapter

Source: https://nuqs.dev/docs/testing

The withNuqsTestingAdapter function is used to wrap components during testing to simulate URL search parameter interactions.

```APIDOC
## withNuqsTestingAdapter

### Description
Initializes a testing adapter for nuqs components, allowing for the simulation of search parameter updates and URL state management.

### Parameters
- **searchParams** (string | URLSearchParams | Record<string, string>) - Optional - The initial search parameters to use for the test.
- **onUrlUpdate** (function) - Optional - A callback function triggered when the URL is updated by the component. Receives an object containing the new URLSearchParams, the rendered query string, and update options.
- **hasMemory** (boolean) - Optional - If true, subsequent URL updates build upon the previous state. Defaults to false (immutable).
- **rateLimitFactor** (number) - Optional - Enables rate limiting in tests if set to 1. Defaults to disabled.
- **resetUrlUpdateQueueOnMount** (boolean) - Optional - Clears the URL update queue before running the test. Defaults to true.
```

--------------------------------

### createStandardSchemaV1(parsers, options)

Source: https://nuqs.dev/docs/utilities

Creates a Standard Schema compatible validator from a search parameter definition object.

```APIDOC
## createStandardSchemaV1

### Description
Converts search parameter definitions into a Standard Schema compatible validator for use with external tools like tRPC or TanStack Router.

### Parameters
- **parsers** (Object) - Required - An object defining the search parameters.
- **options** (Object) - Optional - Configuration options.
  - **partialOutput** (boolean) - Optional - If true, marks the output as Partial, useful for integration with tools like TanStack Router.

### Example
```ts
import { createStandardSchemaV1 } from 'nuqs';

const validateSearchParams = createStandardSchemaV1(searchParams, {
  partialOutput: true
});
```
```

--------------------------------

### Generate Canonical URL for Content-Defining Query Strings

Source: https://nuqs.dev/docs/seo

Use nuqs/server utilities to serialize canonical URLs that include relevant query parameters for content-driven pages.

```ts
import type { Metadata, ResolvingMetadata } from 'next'
import { notFound } from "next/navigation";
import {
  createParser,
  parseAsString,
  createLoader,
  createSerializer,
  type SearchParams,
  type UrlKeys
} from 'nuqs/server'

const youTubeVideoIdRegex = /^[^"&?\/\s]{11}$/i
const youTubeSearchParams = {
  videoId: createParser({
    parse(query) {
      if (!youTubeVideoIdRegex.test(query)) {
        return null
      }
      return query
    },
    serialize(videoId) {
      return videoId
    }
  })
}
const youTubeUrlKeys: UrlKeys<typeof youTubeSearchParams> = {
  videoId: 'v'
}
const loadYouTubeSearchParams = createLoader(
  youTubeSearchParams,
  {
    urlKeys: youTubeUrlKeys
  }
)
const serializeYouTubeSearchParams = createSerializer(
  youTubeSearchParams,
  {
    urlKeys: youTubeUrlKeys
  }
)

// --

type Props = {
  searchParams: Promise<SearchParams>
}

export async function generateMetadata({
  searchParams
}: Props): Promise<Metadata> {
  const { videoId } = await loadYouTubeSearchParams(searchParams)
  if (!videoId) {
    notFound()
  }
  return {
    alternates: {
      canonical: serializeYouTubeSearchParams('/watch', { videoId })
      // /watch?v=dQw4w9WgXcQ
    }
  }
}
```

--------------------------------

### Parser Testing Utilities

Source: https://nuqs.dev/docs/testing

Functions to verify that custom parsers are bijective, ensuring that parse and serialize operations are consistent.

```APIDOC
## Parser Testing Utilities

### Description
Utilities to test custom parsers created with `createParser`. These functions verify bijectivity by checking `parse(serialize(x)) === x` and `serialize(parse(x)) === x`.

### Functions
- **isParserBijective(parser, serialized, value)**: Returns true if the parser is bijective, otherwise throws an error.
- **testParseThenSerialize(parser, serialized)**: Tests the parse-then-serialize flow.
- **testSerializeThenParse(parser, value)**: Tests the serialize-then-parse flow.

### Example
```ts
import { isParserBijective, testParseThenSerialize, testSerializeThenParse } from 'nuqs/testing'

expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true)
expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true)
expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true)
```
```

--------------------------------

### Create a Standard Schema validator

Source: https://nuqs.dev/docs/utilities

Convert search parameter definitions into a Standard Schema compatible validator for use with external tools.

```ts
// [!code word:validateSearchParams]
import {
  createStandardSchemaV1,
  parseAsInteger,
  parseAsString,
} from 'nuqs' // or 'nuqs/server'

// 1. Define your search params as usual
export const searchParams = {
  searchTerm: parseAsString.withDefault(''),
  maxResults: parseAsInteger.withDefault(10)
}

// 2. Then create a Standard Schema compatible validator
export const validateSearchParams = createStandardSchemaV1(searchParams)

// 3. Use it with other tools, like tRPC:
router({
  search: publicProcedure.input(validateSearchParams).query(...)
})
```

--------------------------------

### Implementing Custom Multi Parsers

Source: https://nuqs.dev/docs/parsers/making-your-own

Defines custom parsers for range and key-value structures, then composes them into a multi-parser for complex query state management.

```tsx
/**
 * 100~200 <=> { gte: 100, lte: 200 }
 * 150     <=> { eq: 150 }
 */
const parseAsFromTo = createParser({
  parse: value => {
    const [min = null, max = null] = value.split('~').map(parseAsInteger.parse)
    if (min === null) return null
    if (max === null) return { eq: min }
    return { gte: min, lte: max }
  },
  serialize: value => {
    return value.eq !== undefined ? String(value.eq) : `${value.gte}~${value.lte}`
  }
})

/**
 * foo:bar <=> { key: 'foo', value: 'bar' }
 */
const parseAsKeyValue = createParser({
  parse: value => {
    const [key, val] = value.split(':')
    if (!key || !val) return null
    return { key, value: val }
  },
  serialize: value => {
    return `${value.key}:${value.value}`
  }
})

const parseAsFilters = <TItem extends {}>(itemParser: SingleParser<TItem>) => {
  return createMultiParser({
    parse: values => {
      const keyValue = values.map(parseAsKeyValue.parse).filter(v => v !== null)

      const result = Object.fromEntries(
        keyValue.flatMap(({ key, value }) => {
          const parsedValue: TItem | null = itemParser.parse(value)
          return parsedValue === null ? [] : [[key, parsedValue]]
        })
      )

      return Object.keys(result).length === 0 ? null : result
    },
    serialize: values => {
      return Object.entries(values).map(([key, value]) => {
        if (!itemParser.serialize) return null
        return parseAsKeyValue.serialize({ key, value: itemParser.serialize(value) })
      }).filter(v => v !== null)
    }
  })
}

const [filters, setFilters] = useQueryState(
  'filters',
  parseAsFilters(parseAsFromTo).withDefault({})
)
```

--------------------------------

### Wrap components with NuqsTestingAdapter

Source: https://nuqs.dev/docs/testing

Use the NuqsTestingAdapter to wrap components that rely on nuqs hooks during testing.

```tsx
// [!code word:NuqsTestingAdapter]
import { NuqsTestingAdapter } from 'nuqs/adapters/testing'

<NuqsTestingAdapter>
  <ComponentsUsingNuqs/>
</NuqsTestingAdapter>
```

--------------------------------

### Dynamic import for CJS compatibility

Source: https://nuqs.dev/docs/migrations/v2

Use dynamic imports if your library cannot be converted to ESM.

```ts
const { useQueryState } = await import('nuqs')
```

--------------------------------

### Migrate queryTypes to individual parsers

Source: https://nuqs.dev/docs/migrations/v2

Replace the deprecated queryTypes object with individual parseAsXYZ exports to improve tree-shaking.

```diff
- import { queryTypes } from 'nuqs'
+ import { parseAsString, parseAsInteger, ... } from 'nuqs'

- useQueryState('q',    queryTypes.string.withOptions({ ... }))
- useQueryState('page', queryTypes.integer.withDefault(1))
+ useQueryState('q',    parseAsString.withOptions({ ... }))
+ useQueryState('page', parseAsInteger.withDefault(1))
```

--------------------------------

### Enable history push for state changes

Source: https://nuqs.dev/docs/options

Configure the history option to 'push' to create a new history entry for each state change, allowing the use of the browser's Back button.

```ts
// Append state changes to history:
// [!code word:history]
useQueryState('foo', { history: 'push' })
```

--------------------------------

### createSerializer(searchParams, options?)

Source: https://nuqs.dev/docs/utilities

Creates a serializer function that converts state objects into query strings based on provided parser definitions.

```APIDOC
## createSerializer(searchParams, options?)

### Description
Creates a function that serializes state values into a query string. This is useful for populating <Link> components or generating URLs with state values.

### Parameters
- **searchParams** (Object) - Required - An object mapping state keys to their respective parsers (e.g., parseAsInteger, parseAsString).
- **options** (Object) - Optional - Configuration object.
  - **urlKeys** (Object) - Optional - Maps internal variable names to shorter keys for the URL.
  - **processUrlSearchParams** (Function) - Optional - A function to modify URLSearchParams before final serialization.

### Usage Example
```ts
import { createSerializer, parseAsInteger, parseAsString } from 'nuqs/server';

const serialize = createSerializer({
  search: parseAsString,
  limit: parseAsInteger
});

const queryString = serialize({ search: 'hello', limit: 10 });
// ?search=hello&limit=10
```
```

--------------------------------

### Demonstrating parser conflicts on a shared key

Source: https://nuqs.dev/docs/troubleshooting

Using different parsers on the same query key causes state synchronization issues where the last update propagates to all hooks.

```ts
const [int] = useQueryState('foo', parseAsInteger)
const [float, setFloat] = useQueryState('foo', parseAsFloat)

setFloat(1.234)

// `int` is now 1.234, instead of 1
```

--------------------------------

### Parsing pagination indexes

Source: https://nuqs.dev/docs/parsers/built-in

Handles pagination indexes by applying a +1 offset to the serialized string and -1 when parsing.

```ts
import { parseAsIndex } from 'nuqs'

const [pageIndex] = useQueryState('page', parseAsIndex.withDefault(0))
```

--------------------------------

### Create a custom hook for query states

Source: https://nuqs.dev/docs/tips-tricks

Encapsulate parser configurations into a custom hook to reuse query state logic across multiple components.

```ts
'use client'

import { useQueryStates, parseAsFloat } from 'nuqs'

export function useCoordinates() {
  return useQueryStates({
    lat: parseAsFloat.withDefault(0),
    lng: parseAsFloat.withDefault(0),
  })
}
```

--------------------------------

### createLoader

Source: https://nuqs.dev/docs/server-side

Creates a loader function to parse search parameters based on a provided descriptor object.

```APIDOC
## createLoader(descriptor)

### Description
Creates a function that parses search parameters into typed state variables. The returned loader function can be used in various server-side environments to extract and parse query strings.

### Parameters
- **descriptor** (Object) - Required - An object mapping keys to parser functions (e.g., parseAsFloat, parseAsInteger).

### Usage Example
```tsx
import { parseAsFloat, createLoader } from 'nuqs/server'

export const coordinatesSearchParams = {
  latitude: parseAsFloat.withDefault(0),
  longitude: parseAsFloat.withDefault(0)
}

export const loadSearchParams = createLoader(coordinatesSearchParams)
```
```

--------------------------------

### Test custom parser bijectivity

Source: https://nuqs.dev/docs/testing

Use testing helpers to verify that custom parsers correctly handle parse and serialize operations.

```ts
// [!code word:isParserBijective]
import {
  isParserBijective,
  testParseThenSerialize,
  testSerializeThenParse
} from 'nuqs/testing'

it('is bijective', () => {
  // Passing tests return true
  expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true)
  // Failing test throws an error
  expect(() => isParserBijective(parseAsInteger, '42', 47)).toThrowError()

  // You can also test either side separately:
  expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true)
  expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true)
  // Those will also throw an error if the test fails,
  // which makes it easier to isolate which side failed:
  expect(() => testParseThenSerialize(parseAsInteger, 'not a number')).toThrowError()
  expect(() => testSerializeThenParse(parseAsInteger, NaN)).toThrowError()
})
```

--------------------------------

### Configure Canonical URL for Local-Only State

Source: https://nuqs.dev/docs/seo

Use the metadata object to specify a canonical URL without query strings when query parameters are used only for local UI state.

```ts
import type { Metadata } from 'next'

export const metadata: Metadata = {
  alternates: {
    canonical: '/url/path/without/querystring'
  }
}
```

--------------------------------

### Define search params cache

Source: https://nuqs.dev/docs/server-side

Create a type-safe cache for search parameters using parsers from 'nuqs/server'.

```ts
import {
  createSearchParamsCache,
  parseAsInteger,
  parseAsString
} from 'nuqs/server'
// Note: import from 'nuqs/server' to avoid the "use client" directive

export const searchParamsCache = createSearchParamsCache({
  // List your search param keys and associated parsers here:
  q: parseAsString.withDefault(''),
  maxResults: parseAsInteger.withDefault(10)
})
```

--------------------------------

### Enable full-page navigation for shallow updates in React SPA

Source: https://nuqs.dev/docs/adapters

Use the fullPageNavigationOnShallowFalseUpdates prop to trigger full-page reloads when shallow: false updates occur, useful for non-JS server-side rendering.

```tsx
// [!code word:fullPageNavigationOnShallowFalseUpdates]
createRoot(document.getElementById('root')!).render(
  <NuqsAdapter fullPageNavigationOnShallowFalseUpdates>
    <App />
  </NuqsAdapter>
)
```

--------------------------------

### Enable scroll on navigation

Source: https://nuqs.dev/docs/options

Opt-in to the default Next.js router behavior of scrolling to the top of the page when updating query state.

```ts
// [!code word:scroll]
useQueryState('foo', { scroll: true })
```

--------------------------------

### Use loader in Next.js Pages Router

Source: https://nuqs.dev/docs/server-side

Parse query parameters within getServerSideProps.

```ts
import type { GetServerSidePropsContext } from 'next'

export async function getServerSideProps({ query }: GetServerSidePropsContext) {
  const { latitude, longitude } = loadSearchParams(query)
  // Do some server-side calculations with the coordinates
  return {
    props: { ... }
  }
}
```

--------------------------------

### loader(input, options)

Source: https://nuqs.dev/docs/server-side

The function returned by createLoader, used to parse search parameters from various input sources.

```APIDOC
## loader(input, options)

### Description
Parses the provided input to extract search parameters based on the descriptor defined in createLoader.

### Parameters
- **input** (String | URL | URLSearchParams | Request | Record) - Required - The source of the search parameters to parse.
- **options** (Object) - Optional - Configuration options.
  - **strict** (boolean) - Optional - If true, throws an error when encountering invalid values instead of returning the default value or null.

### Supported Input Types
- Fully qualified URL strings
- Search param strings (e.g., '?foo=bar')
- URL objects
- URLSearchParams objects
- Request objects
- Record<string, string | string[] | undefined>
- Promises of any of the above
```

--------------------------------

### Update debug configuration

Source: https://nuqs.dev/docs/migrations/v2

Run this snippet in the browser console to update the localStorage debug flag from the legacy package name to the new one.

```ts
if (localStorage.debug) {
  localStorage.debug = localStorage.debug.replace('next-usequerystate', 'nuqs')
}
```

--------------------------------

### Abstracting key/parser pairs into a custom hook

Source: https://nuqs.dev/docs/troubleshooting

Encapsulate key and parser logic into a single hook to prevent state conflicts and derive values safely.

```ts
function useIntFloat() {
  const [float, setFloat] = useQueryState('foo', parseAsFloat)
  const int = Math.floor(float)
  return [{int, float}, setFloat] as const
}
```

--------------------------------

### Syncing state with URL using useQueryState

Source: https://nuqs.dev/docs/basic-usage

Replaces React.useState to bind component state to a URL query parameter. Setting the state to null removes the key from the URL.

```tsx
'use client'

import { useQueryState } from 'nuqs'

export function Demo() {
  const [name, setName] = useQueryState('name')
  return (
    <>
      <input value={name || ''} onChange={e => setName(e.target.value)} />
      <button onClick={() => setName(null)}>Clear</button>
      <p>Hello, {name || 'anonymous visitor'}!</p>
    </>
  )
}
```

--------------------------------

### Built-in Parsers

Source: https://nuqs.dev/docs/parsers

Overview of available built-in parsers for converting search parameters into specific data types.

```APIDOC
## Built-in Parsers

### Description
Parsers allow you to convert URL search parameters from their default string format into typed values such as integers, floats, or custom types.

### Available Parsers
- **parseAsString**: Returns the string value as-is.
- **parseAsInteger**: Parses the string as a base-10 integer.
- **parseAsFloat**: Parses the string as a floating-point number.
- **parseAsHex**: Encodes/decodes integers in hexadecimal format.
- **parseAsIndex**: Parses an integer with a +1 offset for zero-indexed pagination.

### Usage Example
```typescript
import { parseAsInteger, parseAsString } from 'nuqs';

// Using a parser with default values
useQueryState('int', parseAsInteger.withDefault(0));

// Using a parser with options
export const searchParamsParsers = {
  q: parseAsString.withDefault('').withOptions({ shallow: false })
};
```
```

--------------------------------

### Create a query string serializer

Source: https://nuqs.dev/docs/utilities

Use createSerializer to generate a function that converts state objects into query strings based on defined parsers.

```ts
// [!code word:createSerializer]
import {
  createSerializer,
  parseAsInteger,
  parseAsIsoDateTime,
  parseAsString,
  parseAsStringLiteral
} from 'nuqs/server' // can also be imported from 'nuqs' in client code

const searchParams = {
  search: parseAsString,
  limit: parseAsInteger,
  from: parseAsIsoDateTime,
  to: parseAsIsoDateTime,
  sortBy: parseAsStringLiteral(['asc', 'desc'])
}

// Create a serializer function by passing the description of the search params to accept
const serialize = createSerializer(searchParams)

// Then later, pass it some values (a subset) and render them to a query string
serialize({
  search: 'foo bar',
  limit: 10,
  from: new Date('2024-01-01'),
  // here, we omit `to`, which won't be added
  sortBy: null // null values are also not rendered
})
// ?search=foo+bar&limit=10&from=2024-01-01T00:00:00.000Z
```

--------------------------------

### Consume custom query state hooks in components

Source: https://nuqs.dev/docs/tips-tricks

Demonstrates reading and updating query states using a custom hook within React components.

```tsx
'use client'

import { useCoordinates } from '../hooks/useCoordinates'

function MapView() {
  const [{ lat, lng }] = useCoordinates() // Read-only
  return (
    <div>
      Latitude: {lat}
      Longitude: {lng}
    </div>
  )
}

function MapControls() {
  const [{ lat, lng }, setCoordinates] = useCoordinates()
  return (
    <div>
      <input
        type="number"
        value={lat}
        onChange={(e) => setCoordinates({ lat: e.target.valueAsNumber })}
      />
      <input
        type="number"
        value={lng}
        onChange={(e) => setCoordinates({ lng: e.target.valueAsNumber })}
      />
    </div>
  )
}
```

--------------------------------

### Integrate NuqsAdapter with React Router v6

Source: https://nuqs.dev/docs/adapters

Wrap the RouterProvider with NuqsAdapter to enable URL query state management in React Router v6 applications.

```tsx
// [!code word:NuqsAdapter]
import { NuqsAdapter } from 'nuqs/adapters/react-router/v6'
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
import App from './App'

const router = createBrowserRouter([
  {
    path: '/',
    element: <App />
  }
])

export function ReactRouter() {
  return (
    <NuqsAdapter>
      <RouterProvider router={router} />
    </NuqsAdapter>
  )
}
```

--------------------------------

### Using UrlKeys type helper

Source: https://nuqs.dev/docs/batching

Reuse parser and urlKeys definitions across components using the UrlKeys type helper.

```ts
// [!code word:UrlKeys]
import { type UrlKeys } from 'nuqs' // or 'nuqs/server'

export const coordinatesParsers = {
  latitude: parseAsFloat.withDefault(45.18),
  longitude: parseAsFloat.withDefault(5.72)
}

export const coordinatesUrlKeys: UrlKeys<typeof coordinatesParsers> = {
  latitude: 'lat',
  longitude: 'lng'
}
```

--------------------------------

### Remapping keys with urlKeys

Source: https://nuqs.dev/docs/batching

Use the urlKeys option to map internal variable names to shorter, URL-friendly keys.

```ts
const [{ latitude, longitude }, setCoordinates] = useQueryStates(
  {
    // Use variable names that make sense in your codebase
    latitude: parseAsFloat.withDefault(45.18),
    longitude: parseAsFloat.withDefault(5.72)
  },
  {
    urlKeys: {
      // And remap them to shorter keys in the URL
      latitude: 'lat',
      longitude: 'lng'
    }
  }
)

// No changes in the setter API, but the keys are remapped to:
// ?lat=45.18&lng=5.72
setCoordinates({
  latitude: 45.18,
  longitude: 5.72
})
```

--------------------------------

### Create a custom parser with an equality function

Source: https://nuqs.dev/docs/parsers/making-your-own

Implements a custom parser for complex objects that requires an eq function to correctly compare state values for options like clearOnDefault.

```ts

// Eg: TanStack Table sorting state
// /?sort=foo:asc → { id: 'foo', desc: false }
const parseAsSort = createParser({
  parse(query) {
    const [key = '', direction = ''] = query.split(':')
    const desc = parseAsStringLiteral(['asc', 'desc']).parse(direction) ?? 'asc'
    return {
      id: key,
      desc: desc === 'desc'
    }
  },
  serialize(value) {
    return `${value.id}:${value.desc ? 'desc' : 'asc'}`
  },
  // [!code highlight:3]
  eq(a, b) {
    return a.id === b.id && a.desc === b.desc
  }
})
```
Tokens:
Raw