nuqs.47ng.com/docs/

Public Link
Created by:
****ad@vlad.studio
Starting URLs:
https://nuqs.47ng.com/docs/installation
CSS Selector:
article
Crawl Prefixes:
https://nuqs.47ng.com/docs/
Exclude Patterns:
https://nuqs.47ng.com/docs/utilities
https://nuqs.47ng.com/docs/troubleshooting
https://nuqs.47ng.com/docs/seo
https://nuqs.47ng.com/docs/about
https://nuqs.47ng.com/docs/migrations/v2
## Page: https://nuqs.47ng.com/docs/installation

# Installation

Getting started

Install the `nuqs` package with your favourite package manager:

    pnpm add nuqs

    npm install nuqs

    yarn add nuqs

    bun add nuqs

## Which version should I use?

`nuqs@^2` supports the following frameworks and their respective versions:

*   Next.js: 14.2.0 and above (including Next.js 15)
*   React SPA: 18.3 & 19
*   Remix: 2 and above
*   React Router v6: `react-router-dom@^6`
*   React Router v7: `react-router@^7`

For older versions of Next.js, you may use `nuqs@^1` (documentation in the README).

Next

Adapters

---

## Page: https://nuqs.47ng.com/docs/adapters

# Adapters

Using nuqs in your React framework of choice

Since version 2, you can now use nuqs in the following React frameworks, by wrapping it with a `NuqsAdapter` context provider:

*   Next.js (app router)
*   Next.js (pages router)
*   React SPA (eg: with Vite)
*   Remix
*   React Router v6
*   React Router v7

## Next.js

### App router

Wrap your `{children}` with the `NuqsAdapter` component in your root layout file:

src/app/layout.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>  ) }

### Pages router

Wrap the `<Component>` page outlet with the `NuqsAdapter` component in your `_app.tsx` file:

src/pages/\_app.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>  ) }

### Unified (router-agnostic)

If your Next.js app uses **both the app and pages routers** and the adapter needs to be mounted in either, you can import the unified adapter, at the cost of a slightly larger bundle size (~100B).

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

  

The main reason for adapters is to open up nuqs to other React frameworks:

## React SPA

Example, with Vite:

src/main.tsx

    import { NuqsAdapter } from 'nuqs/adapters/react'   createRoot(document.getElementById('root')!).render(  <NuqsAdapter>  <App />  </NuqsAdapter> )

Note: because there is no known server in this configuration, the `shallow: false` option will have no effect.

Since `nuqs@2.4.0`, you can specify a flag to perform a full-page navigation when updating query state configured with `shallow: false`, to notify the web server that the URL state has changed, if it needs it for server-side rendering other parts of the application than the static React bundle:

src/main.tsx

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

This may be useful for servers not written in JavaScript, like Django (Python), Rails (Ruby), Laravel (PHP), Phoenix (Elixir) etc…

## Remix

app/root.tsx

    import { NuqsAdapter } from 'nuqs/adapters/remix'   // ...   export default function App() {  return (  <NuqsAdapter>  <Outlet />  </NuqsAdapter>  ) }

## React Router v6

src/main.tsx

    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>  ) }

Only `BrowserRouter` is supported. There may be support for `HashRouter` in the future (see issue #810), but support for `MemoryRouter` is not planned.

## React Router v7

app/root.tsx

    import { NuqsAdapter } from 'nuqs/adapters/react-router/v7' import { Outlet } from 'react-router'   // ...   export default function App() {  return (  <NuqsAdapter>  <Outlet />  </NuqsAdapter>  ) }

Deprecation notice

The generic import `nuqs/adapters/react-router` (pointing to v6) is deprecated and will be removed in nuqs@3.0.0.

Please pin your imports to the specific version, eg: `nuqs/adapters/react-router/v6` or `nuqs/adapters/react-router/v7`.

The main difference is where the React Router hooks are imported from: `react-router-dom` for v6, and `react-router` for v7.

## Testing

Documentation for the `NuqsTestingAdapter` is on the testing page.

Previous

Installation

Next

Basic usage

---

## Page: https://nuqs.47ng.com/docs/basic-usage

# Basic usage

Replacing React.useState with useQueryState

Prerequisite

Have you setup your app with the appropriate **adapter**? Then you are all set!

If you are using `React.useState` to manage your local UI state, you can replace it with `useQueryState` to sync it with the URL.

    '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>  </>  ) }

<empty query>

Hello, anonymous visitor!Clear

`useQueryState` takes one required argument: the key to use in the query string.

Like `React.useState`, it returns an array with the value present in the query string as a string (or `null` if none was found), and a state updater function.

Example outputs for our demo example:

| URL | name value | Notes |
| --- | --- | --- |
| `/` | `null` | No `name` key in URL |
| `/?name=` | `''` | Empty string |
| `/?name=foo` | `'foo'` |  |
| `/?name=2` | `'2'` | Always returns a string by default, see Parsers |

Tip

Setting `null` as a value will remove the key from the query string.

## Default values

When the query string is not present in the URL, the default behaviour is to return `null` as state.

It can make state updating and UI rendering tedious. Take this example of a simple counter stored in the URL:

    import { useQueryState, parseAsInteger } from 'nuqs'   export default () => {  const [count, setCount] = useQueryState('count', parseAsInteger)  return (  <>  <pre>count: {count}</pre>  <button onClick={() => setCount(0)}>Reset</button>  {/* handling null values in setCount is annoying: */}  <button onClick={() => setCount(c => (c ?? 0) + 1)}>+</button>  <button onClick={() => setCount(c => (c ?? 0) - 1)}>-</button>  <button onClick={() => setCount(null)}>Clear</button>  </>  ) }

You can provide a default value as the second argument to `useQueryState` (or via the `.withDefault` builder method on parsers):

    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

It makes it much easier to handle state updates:

    const increment = () => setCount(c => c + 1) // c will never be null const decrement = () => setCount(c => c - 1) // c will never be null const clearCount = () => setCount(null) // Remove query from the URL

Note

The default value is internal to React, it will **not** be written to the URL _unless you set it explicitly_ and use the `clearOnDefault: false` option.

Tip

The default value is also returned if the value is _invalid_ for the parser.

Tip

Setting the state to `null` when a default value is specified:

1.  Clears the query from the URL
2.  Returns the default value as state

Previous

Adapters

Next

Built-in parsers

---

## Page: https://nuqs.47ng.com/docs/options

# Options

Configuring nuqs

By default, `nuqs` will update search params:

1.  On the client only (not sending requests to the server),
2.  by replacing the current history entry,
3.  and without scrolling to the top of the page.

These behaviours can be configured, along with a few additional options.

## Passing options

Options can be passed at the hook level via the builder pattern:

    const [state, setState] = useQueryState(  'foo',  parseAsString.withOptions({ history: 'push' }) )

Or when calling the state updater function, as a second parameter:

    setState('foo', { scroll: true })

Call-level options will override hook level options.

## History

By default, state updates are done by **replacing** the current history entry with the updated query when state changes.

You can see this as a sort of `git squash`, where all state-changing operations are merged into a single browsing history entry.

You can also opt-in to **push** a new history entry for each state change, per key, which will let you use the Back button to navigate state updates:

    // Append state changes to history: useQueryState('foo', { history: 'push' })

Watch out!

Breaking the Back button can lead to a bad user experience. Make sure to use this option only if the search params to update contribute to a navigation-like experience (eg: tabs, modals). Overriding the Back behaviour must be a UX enhancement rather than a nuisance.

_— “With great power comes great responsibility.”_

## Shallow

By default, query state updates are done in a _client-first_ manner: there are no network calls to the server.

This is equivalent to the `shallow` option of the Next.js router set to `true`.

To opt-in to notifying the server on query updates, you can set `shallow` to `false`:

    useQueryState('foo', { shallow: false })

Note that the shallow option only makes sense if your page can be server-side rendered. Therefore, it has no effect in React SPA.

For server-side renderable frameworks, you would pair `shallow: false` with:

*   In Next.js app router: the `searchParams` page prop to render the RSC tree based on the updated query state.
*   In Next.js pages router: the `getServerSideProps` function
*   In Remix & React Router: a `loader` function

### In React Router based frameworks

While the `shallow: false` default behaviour is uncommon for Remix and React Router, where loaders are always supposed to run on URL changes, nuqs gives you control of this behaviour, by opting in to running loaders only if they do need to access the relevant search params.

One caveat is that the stock `useSearchParams` hook from those frameworks doesn’t reflect shallow-updated search params, so we provide you with one that does:

    import { useOptimisticSearchParams } from 'nuqs/adapters/remix' // or '…/react-router/v6' or '…/react-router/v7'   function Component() {  // Note: this is read-only, but reactive to all URL changes  const searchParams = useOptimisticSearchParams()  return <div>{searchParams.get('foo')}</div> }

This concept of _“shallow routing”_ is done via updates to the browser’s History API.

Why not using shouldRevalidate?

`shouldRevalidate` is the idomatic way of opting out of running loaders on navigation, but nuqs uses the opposite approach: opting in to running loaders only when needed.

In order to avoid specifying `shouldRevalidate` for every route, nuqs chose to patch the history methods to enable shallow routing by default (on its own updates) in React Router based frameworks.

## Scroll

The Next.js router scrolls to the top of the page on navigation updates, which may not be desirable when updating the query string with local state.

Query state updates won’t scroll to the top of the page by default, but you can opt-in to this behaviour:

    useQueryState('foo', { scroll: true })

## Throttling URL updates

Because of browsers rate-limiting the History API, updates **to the URL** are queued and throttled to a default of 50ms, which seems to satisfy most browsers even when sending high-frequency query updates, like binding to a text input or a slider.

Safari’s rate limits are much higher and require a throttle of 120ms (320ms for older versions of Safari).

If you want to opt-in to a larger throttle time — for example to reduce the amount of requests sent to the server when paired with `shallow: false` — you can specify it under the `throttleMs` option:

    useQueryState('foo', {  // Send updates to the server maximum once every second  shallow: false,  throttleMs: 1000 })

Note

the state returned by the hook is always updated **instantly**, to keep UI responsive. Only changes to the URL, and server requests when using `shallow: false`, are throttled.

If multiple hooks set different throttle values on the same event loop tick, the highest value will be used. Also, values lower than 50ms will be ignored, to avoid rate-limiting issues. Read more.

Specifying a `+Infinity` value for `throttleMs` will **disable** updates to the URL or the server, but all `useQueryState(s)` hooks will still update their internal state and stay in sync with each other.

## Transitions

When combined with `shallow: false`, you can use React’s `useTransition` hook to get loading states while the server is re-rendering server components with the updated URL.

Pass in the `startTransition` function from `useTransition` to the options to enable this behaviour:

    'use client'   import React from 'react' import { useQueryState, parseAsString } from 'nuqs'   function ClientComponent({ data }) {  // 1. Provide your own useTransition hook:  const [isLoading, startTransition] = React.useTransition()  const [query, setQuery] = useQueryState(  'query',  // 2. Pass the `startTransition` as an option:  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> }

In `nuqs@1.x.x`, passing `startTransition` as an option automatically sets `shallow: false`.

This is no longer the case in `nuqs@>=2.0.0`: you’ll need to set it explicitly.

## Clear on default

When the state is set to the default value, the search parameter is removed from the URL, instead of being reflected explicitly.

However, sometimes you might want to keep the search parameter in the URL, because **default values _can_ change**, and the meaning of the URL along with it.

Example of defaults changing

In `nuqs@1.x.x`, `clearOnDefault` was `false` by default.  
in `nuqs@2.0.0`, `clearOnDefault` is now `true` by default, in response to user feedback.

If you want to keep the search parameter in the URL when it’s set to the default value, you can set `clearOnDefault` to `false`:

    useQueryState('search', {  defaultValue: '',  clearOnDefault: false })

Tip

Clearing the key-value pair from the query string can always be done by setting the state to `null`.

This option compares the set state against the default value using `===` reference equality, so if you are using a custom parser for a state type that wouldn’t work with reference equality, you should provide the `eq` function to your parser (this is done for you in built-in parsers):

    const dateParser = createParser({  parse: (value: string) => new Date(value.slice(0, 10)),  serialize: (date: Date) => date.toISOString().slice(0, 10),  eq: (a: Date, b: Date) => a.getTime() === b.getTime()  })

Previous

TanStack Table Parsers

Next

useQueryStates

---

## Page: https://nuqs.47ng.com/docs/batching

# useQueryStates

How to read & update multiple search params at once

## Multiple updates (batching)

You can call as many state update functions as needed in a single event loop tick, and they will be applied to the URL asynchronously:

    const MultipleQueriesDemo = () => {  const [lat, setLat] = useQueryState('lat', parseAsFloat)  const [lng, setLng] = useQueryState('lng', parseAsFloat)  const randomCoordinates = React.useCallback(() => {  setLat(Math.random() * 180 - 90)  setLng(Math.random() * 360 - 180)  }, []) }

If you wish to know when the URL has been updated, and what it contains, you can await the Promise returned by the state updater function, which gives you the updated URLSearchParameters object:

    const randomCoordinates = React.useCallback(() => {  setLat(42)  return setLng(12) }, [])   randomCoordinates().then((search: URLSearchParams) => {  search.get('lat') // 42  search.get('lng') // 12, has been queued and batch-updated })

_Implementation details (Promise caching)_

The returned Promise is cached until the next flush to the URL occurs, so all calls to a setState (of any hook) in the same event loop tick will return the same Promise reference.

Due to throttling of calls to the Web History API, the Promise may be cached for several ticks. Batched updates will be merged and flushed once to the URL. This means not every setState will reflect to the URL, if another one comes overriding it before flush occurs.

The returned React state will reflect all set values instantly, to keep UI responsive.

* * *

## `useQueryStates`

For query keys that should always move together, you can use `useQueryStates` with an object containing each key’s type:

    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 })

### Options

There are three places you can define options in `useQueryStates`:

*   As the second argument to the hook itself (global options, like `history: 'push'` above)
*   On each parser, like `parseAsFloat.withOptions({ shallow: false })`
*   At the call level when updating the state:

    setCoordinates(  {  lat: 42,  lng: 12  },  {  shallow: false  } )

The order of precedence is: call-level options > parser options > global options.

Tip

You can clear all keys managed by a `useQueryStates` hook by passing `null` to the state updater function.

    const clearAll = () => setCoordinates(null)

This will clear `lat` & `lng`, and leave other search params untouched.

### Shorter search params keys

One issue with tying the parsers object keys to the search params keys was that you had to trade-off between variable names that make sense for your domain or business logic, and short, URL-friendly keys.

In `nuqs@1.20.0` and later, you can use a `urlKeys` object in the hook options to remap the variable names to shorter keys:

    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 })

As your application grows, you may want to reuse these parsers and urlKeys definitions across multiple components or nuqs features (like loaders or a serializer).

You can use the `UrlKeys` type helper for this:

    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' }

Previous

Options

Next

Server-Side usage

---

## Page: https://nuqs.47ng.com/docs/server-side

# Server-Side usage

Type-safe search params on the server

## Loaders

To parse search params server-side, you can use a _loader_ function.

You create one using the `createLoader` function, by passing it your search params descriptor object:

searchParams.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)

Here, `loadSearchParams` is a function that parses search params and returns state variables to be consumed server-side (the same state type that `useQueryStates` returns).

Next.js (app router)Next.js (pages router)API routesRemix / React RouterReact / client-side

app/page.tsx

    import { loadSearchParams } from './search-params' import type { SearchParams } from 'nuqs/server'   type PageProps = {  searchParams: Promise<SearchParams> }   export default async function Page({ searchParams }: PageProps) {  const { latitude, longitude } = await loadSearchParams(searchParams)  return <Map  lat={latitude}  lng={longitude}  />    // Pro tip: you don't *have* to await the result.  // Pass the Promise object to children components wrapped in <Suspense>  // to benefit from PPR / dynamicIO and serve a static outer shell  // immediately, while streaming in the dynamic parts that depend on  // the search params when they become available. }

Note

Loaders **don’t validate** your data. If you expect positive integers or JSON-encoded objects of a particular shape, you’ll need to feed the result of the loader to a schema validation library, like Zod.

Built-in validation support is coming. Read the RFC. Alternatively, you can build validation into custom parsers.

The loader function will accept the following input types to parse search params from:

*   A string containing a fully qualified URL: `https://example.com/?foo=bar`
*   A string containing just search params: `?foo=bar` (like `location.search`)
*   A `URL` object
*   A `URLSearchParams` object
*   A `Request` object
*   A `Record<string, string | string[] | undefined>` (eg: `{ foo: 'bar' }`)
*   A `Promise` of any of the above, in which case it also returns a Promise.

## Cache

This feature is available for Next.js only.

If you wish to access the searchParams in a deeply nested Server Component (ie: not in the Page component), you can use `createSearchParamsCache` to do so in a type-safe manner.

Think of it as a loader combined with a way to propagate the parsed values down the RSC tree, like Context would on the client.

searchParams.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) })

page.tsx

    import { searchParamsCache } from './searchParams' import { type SearchParams } from 'nuqs/server'   type PageProps = {  searchParams: Promise<SearchParams> // Next.js 15+: async searchParams prop }   export default async function Page({ searchParams }: PageProps) {  // ⚠️ Don't forget to call `parse` here.  // You can access type-safe values from the returned object:  const { q: query } = await searchParamsCache.parse(searchParams)  return (  <div>  <h1>Search Results for {query}</h1>  <Results />  </div>  ) }   function Results() {  // Access type-safe search params in children server components:  const maxResults = searchParamsCache.get('maxResults')  return <span>Showing up to {maxResults} results</span> }

The cache will only be valid for the current page render (see React’s `cache` function).

Note: the cache only works for **server components**, but you may share your parser declaration with `useQueryStates` for type-safety in client components:

searchParams.ts

    import {  parseAsFloat,  createSearchParamsCache } from 'nuqs/server'   export const coordinatesParsers = {  lat: parseAsFloat.withDefault(45.18),  lng: parseAsFloat.withDefault(5.72) } export const coordinatesCache = createSearchParamsCache(coordinatesParsers)

page.tsx

    import { coordinatesCache } from './searchParams' import { Server } from './server' import { Client } from './client'   export default async function Page({ searchParams }) {  await coordinatesCache.parse(searchParams)  return (  <>  <Server />  <Suspense>  <Client />  </Suspense>  </>  ) }

server.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>  ) }

client.tsx

    'use client'   import { useQueryStates } from 'nuqs' import { coordinatesParsers } from './searchParams'   export function Client() {  const [{ lat, lng }, setCoordinates] = useQueryStates(coordinatesParsers)  // ... }

### Shorter search params keys

Just like `useQueryStates`, you can define a `urlKeys` object to map the variable names defined by the parser to shorter keys in the URL. They will be translated on read and your codebase can only refer to variable names that make sense for your domain or business logic.

searchParams.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'  } })

Previous

useQueryStates

Next

Limits

---

## Page: https://nuqs.47ng.com/docs/limits

# Limits

There are some limits you should be aware of when using nuqs or URL params in general.

## URL update throttling

Browsers rate-limit the History API, updates to the URL are queued and throttled to a default of 50ms, which seems to satisfy most browsers even when sending high-frequency query updates, like binding to a text input or a slider.

Safari’s rate limits are much higher and require a throttle of 120ms (320ms for older versions of Safari).

Nuqs handles this out of the box so you don’t run into those rate-limits, however it is possible to set your own custom throttles.

For more info how to set custom throttles see Throttling URL updates.

## Max URL lengths

Most modern browsers enforce a max URL length, which can vary:

*   **Chrome:** ~2 MB (practically, you might encounter issues at around 2,000 characters).
*   **Firefox:** ~65,000 characters.
*   **Safari:** Generally has more restrictive limits (around 80,000 characters).
*   **IE/Edge:** Historically limited to 2,083 characters (IE), although Edge has relaxed this limit.

Additionally, transport mechanisms like social media, messaging apps, and emails may impose significantly lower limits on URL length. Long URLs may be truncated, wrapped, or rendered unusable when shared on these platforms.

Keep in mind that not all application state should be stored in URLs. Exceeding the 2,000-character range may indicate the need to reconsider your state management approach.

Previous

Server-Side usage

Next

Utilities

---

## Page: https://nuqs.47ng.com/docs/debugging

# Debugging

Enabling debug logs and user timings markers

You can enable debug logs in the browser by setting the `debug` item in localStorage to `nuqs`, and reload the page.

    // In your devtools: localStorage.setItem('debug', 'nuqs')

> Note: unlike the `debug` package, this will not work with wildcards, but you can combine it: `localStorage.setItem('debug', '*,nuqs')`

Log lines will be prefixed with `[nuqs]` for `useQueryState` and `[nuq+]` for `useQueryStates`, along with other internal debug logs.

User timings markers are also recorded, for advanced performance analysis using your browser’s devtools.

Providing debug logs when opening an issue is always appreciated. 🙏

Previous

Utilities

Next

Testing

---

## Page: https://nuqs.47ng.com/docs/testing

# Testing

Some tips on testing components that use \`nuqs\`

Since nuqs 2, you can unit-test components that use `useQueryState(s)` hooks without needing to mock anything, by using a dedicated testing adapter that will facilitate **setting up** your tests (with initial search params) and **asserting** on URL changes when **acting** on your components.

## Testing hooks with React Testing Library

When testing hooks that rely on nuqs’ `useQueryState(s)` with React Testing Library’s `renderHook` function, you can use `withNuqsTestingAdapter` to get a wrapper component to pass to the `renderHook` call:

    import { withNuqsTestingAdapter } from 'nuqs/adapters/testing'   const { result } = renderHook(() => useTheHookToTest(), {  wrapper: withNuqsTestingAdapter({  searchParams: { count: "42" },  }), })

## Testing components with Vitest

Here is an example for Vitest and Testing Library to test a button rendering a counter:

Vitest v1Vitest v2

counter-button.test.tsx

    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') })

See issue #259 for more testing-related discussions.

## Jest and ESM

Since nuqs 2 is an ESM-only package, there are a few hoops you need to jump through to make it work with Jest. This is extracted from the Jest ESM guide.

1.  Add the following options to your jest.config.ts file:

jest.config.ts

    const config: Config = {  // <Other options here>  extensionsToTreatAsEsm: [".ts", ".tsx"],  transform: {} };

2.  Change your test command to include the `--experimental-vm-modules` flag:

package.json

    {  "scripts": {  "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"  } }

Adapt accordingly for Windows with `cross-env`.

## API

`withNuqsTestingAdapter` accepts the following arguments:

*   `searchParams`: The initial search params to use for the test. These can be a query string, a `URLSearchParams` object or a record object with string values.

    withNuqsTestingAdapter({  searchParams: '?q=hello&limit=10' })   withNuqsTestingAdapter({  searchParams: new URLSearchParams('?q=hello&limit=10') })   withNuqsTestingAdapter({  searchParams: {  q: 'hello',  limit: '10' // Values are serialized strings  } })

*   `onUrlUpdate`: a function that will be called when the URL is updated by the component. It receives an object with:
    *   the new search params as an instance of `URLSearchParams`
    *   the new rendered query string (for convenience)
    *   the options used to update the URL.

🧪 Internal/advanced options

*   `rateLimitFactor`. By default, rate limiting is disabled when testing, as it can lead to unexpected behaviours. Setting this to 1 will enable rate limiting with the same factor as in production.
    
*   `resetUrlUpdateQueueOnMount`: clear the URL update queue before running the test. This is `true` by default to isolate tests, but you can set it to `false` to keep the URL update queue between renders and match the production behaviour more closely.
    

## NuqsTestingAdapter

The `withNuqsTestingAdapter` function is a wrapper component factory function wraps children with a `NuqsTestingAdapter`, but you can also use it directly:

    import { NuqsTestingAdapter } from 'nuqs/adapters/testing'   <NuqsTestingAdapter>  <ComponentsUsingNuqs/> </NuqsTestingAdapter>

It takes the same props as the arguments you can pass to `withNuqsTestingAdapter`.

## Testing custom parsers

If you create custom parsers with `createParser`, you will likely want to test them.

Parsers should:

1.  Define pure functions for `parse`, `serialize`, and `eq`.
2.  Be bijective: `parse(serialize(x)) === x` and `serialize(parse(x)) === x`.

To help test bijectivity, you can use helpers defined in `nuqs/testing`:

    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() })

Previous

Debugging

Next

Troubleshooting

---

## Page: https://nuqs.47ng.com/docs/tips-tricks

# Tips and tricks

A collection of good practices and tips to help you get the most out of nuqs

## Reusing hooks

If you find yourself reusing the same hooks in multiple components, you can create a custom hook to encapsulate the parser configuration.

Tip

All query states bound to the same key will be synchronized across components.

hooks/useCoordinates.ts

    'use client'   import { useQueryStates, parseAsFloat } from 'nuqs'   export function useCoordinates() {  return useQueryStates({  lat: parseAsFloat.withDefault(0),  lng: parseAsFloat.withDefault(0),  }) }

components/Map.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>  ) }

Previous

SEO

Next

About

---

## Page: https://nuqs.47ng.com/docs/parsers

Parsers

# Built-in parsers

When using strings is not enough

Search params are strings by default, but chances are your state is more complex than that.

You might want to use numbers, booleans, Dates, objects, arrays, or even custom types. This is where **parsers** come in.

`nuqs` provides built-in parsers for the most common types, and allows you to define your own.

## String

    import { parseAsString } from 'nuqs'

<empty query>

Clear

Type-safety tip

`parseAsString` is a noop: it does not perform any validation when parsing, and will accept **any** value.

If you’re expecting a certain set of string values, like `'foo' | 'bar'`, see Literals for ensuring type-runtime safety.

If search params are strings by default, what’s the point of this _“parser”_ ?

It becomes useful if you’re declaring a search params object, and/or you want to use the builder pattern to specify default values and options:

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

## Numbers

### Integers

Transforms the search param string into an integer with `parseInt` (base 10).

    import { parseAsInteger } from 'nuqs'   useQueryState('int', parseAsInteger.withDefault(0))

<empty query>

Clear

### Floating point

Same as integer, but uses `parseFloat` under the hood.

    import { parseAsFloat } from 'nuqs'   useQueryState('float', parseAsFloat.withDefault(0))

<empty query>

Clear

### Hexadecimal

Encodes integers in hexadecimal.

    import { parseAsHex } from 'nuqs'   useQueryState('hex', parseAsHex.withDefault(0x00))

<empty query>

Clear

Going further

Check out the Hex Colors playground for a demo.

### Index

Same as integer, but adds a `+1` offset to the serialized querystring (and `-1` when parsing). Useful for pagination indexes.

    import { parseAsIndex } from 'nuqs'   const [pageIndex] = useQueryState('page', parseAsIndex.withDefault(0))

<empty query>

*   Previous
*   1
*   2
*   3
*   4
*   5
*   Next

    pageIndex: 0 // internal state is zero-indexed

Clear

## Boolean

    import { parseAsBoolean } from 'nuqs'   useQueryState('bool', parseAsBoolean.withDefault(false))

<empty query>

Checked: `false`Clear

## Literals

These parsers extend the basic integer and float parsers, but test against some expected valid values, defined as TypeScript literals.

Note

Don’t forget the `as const` when declaring your expected values.

### String literals

    import { parseAsStringLiteral } from 'nuqs'   // List accepted values const sortOrder = ['asc', 'desc'] as const   // Then pass it to the parser parseAsStringLiteral(sortOrder)   // Optional: extract the type from them type SortOrder = (typeof sortOrder)[number] // 'asc' | 'desc'

<empty query>

No order definedClear

### Numeric literals

    import { parseAsNumberLiteral } from 'nuqs'   // List accepted values const diceSides = [1, 2, 3, 4, 5, 6] as const   // Then pass it to the parser parseAsNumberLiteral(diceSides)

## Enums

String enums are a bit more verbose than string literals, but `nuqs` supports them.

    enum Direction {  up = 'UP',  down = 'DOWN',  left = 'LEFT',  right = 'RIGHT' }   parseAsStringEnum<Direction>(Object.values(Direction))

Note

The query string value will be the **value** of the enum, not its name (here: `?direction=UP`).

## Dates & timestamps

There are three parsers that give you a `Date` object, their difference is on how they encode the value into the query string.

### ISO 8601 Datetime

    import { parseAsIsoDateTime } from 'nuqs'

<empty query>

UTC

NowClear

### ISO 8601 Date

    import { parseAsIsoDate } from 'nuqs'

<empty query>

UTC

NowClear

The Date is parsed without the time zone offset, making it at 00:00:00 UTC.

  
_Support: introduced in version 2.1.0._

### Timestamp

Miliseconds since the Unix epoch.

    import { parseAsTimestamp } from 'nuqs'

<empty query>

UTC

NowClear

## Arrays

All of the parsers on this page can be used to parse arrays of their respective types.

    import { parseAsArrayOf, parseAsInteger } from 'nuqs'   parseAsArrayOf(parseAsInteger)   // Optionally, customise the separator parseAsArrayOf(parseAsInteger, ';')

## JSON

If primitive types are not enough, you can encode JSON in the query string.

Pass it a validation function to validate and infer the type of the parsed data, like a Zod schema:

    import { parseAsJson } from 'nuqs' import { z } from 'zod'   const schema = z.object({  pkg: z.string(),  version: z.number(),  worksWith: z.array(z.string()) })   // This parser is a function, don't forget to call it with the parse function // as an argument. const [json, setJson] = useQueryState('json', parseAsJson(schema.parse))   setJson({  pkg: 'nuqs',  version: 2,  worksWith: ['Next.js', 'React', 'Remix', 'React Router', 'and more'] })

<empty query>

null

Try itClear

Using other validation libraries is possible, as long as they throw an error when the data is invalid (eg: Valibot, Yup, etc).

## Using parsers server-side

For shared code that may be imported in the Next.js app router, you should import parsers from `nuqs/server` to use them in both server & client code, as it doesn’t include the `'use client'` directive.

    import { parseAsString } from 'nuqs/server'

Importing from `nuqs` will only work in client code, and will throw bundling errors when using functions (like `.withDefault` & `.withOptions`) across shared code.

For all other frameworks, you can use either interchangeably, as they don’t care about the `'use client'` directive.

Previous

Basic usage

Next

Custom parsers

---

## Page: https://nuqs.47ng.com/docs/parsers/built-in

Parsers

# Built-in parsers

When using strings is not enough

Search params are strings by default, but chances are your state is more complex than that.

You might want to use numbers, booleans, Dates, objects, arrays, or even custom types. This is where **parsers** come in.

`nuqs` provides built-in parsers for the most common types, and allows you to define your own.

## String

    import { parseAsString } from 'nuqs'

<empty query>

Clear

Type-safety tip

`parseAsString` is a noop: it does not perform any validation when parsing, and will accept **any** value.

If you’re expecting a certain set of string values, like `'foo' | 'bar'`, see Literals for ensuring type-runtime safety.

If search params are strings by default, what’s the point of this _“parser”_ ?

It becomes useful if you’re declaring a search params object, and/or you want to use the builder pattern to specify default values and options:

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

## Numbers

### Integers

Transforms the search param string into an integer with `parseInt` (base 10).

    import { parseAsInteger } from 'nuqs'   useQueryState('int', parseAsInteger.withDefault(0))

<empty query>

Clear

### Floating point

Same as integer, but uses `parseFloat` under the hood.

    import { parseAsFloat } from 'nuqs'   useQueryState('float', parseAsFloat.withDefault(0))

<empty query>

Clear

### Hexadecimal

Encodes integers in hexadecimal.

    import { parseAsHex } from 'nuqs'   useQueryState('hex', parseAsHex.withDefault(0x00))

<empty query>

Clear

Going further

Check out the Hex Colors playground for a demo.

### Index

Same as integer, but adds a `+1` offset to the serialized querystring (and `-1` when parsing). Useful for pagination indexes.

    import { parseAsIndex } from 'nuqs'   const [pageIndex] = useQueryState('page', parseAsIndex.withDefault(0))

<empty query>

*   Previous
*   1
*   2
*   3
*   4
*   5
*   Next

    pageIndex: 0 // internal state is zero-indexed

Clear

## Boolean

    import { parseAsBoolean } from 'nuqs'   useQueryState('bool', parseAsBoolean.withDefault(false))

<empty query>

Checked: `false`Clear

## Literals

These parsers extend the basic integer and float parsers, but test against some expected valid values, defined as TypeScript literals.

Note

Don’t forget the `as const` when declaring your expected values.

### String literals

    import { parseAsStringLiteral } from 'nuqs'   // List accepted values const sortOrder = ['asc', 'desc'] as const   // Then pass it to the parser parseAsStringLiteral(sortOrder)   // Optional: extract the type from them type SortOrder = (typeof sortOrder)[number] // 'asc' | 'desc'

<empty query>

No order definedClear

### Numeric literals

    import { parseAsNumberLiteral } from 'nuqs'   // List accepted values const diceSides = [1, 2, 3, 4, 5, 6] as const   // Then pass it to the parser parseAsNumberLiteral(diceSides)

## Enums

String enums are a bit more verbose than string literals, but `nuqs` supports them.

    enum Direction {  up = 'UP',  down = 'DOWN',  left = 'LEFT',  right = 'RIGHT' }   parseAsStringEnum<Direction>(Object.values(Direction))

Note

The query string value will be the **value** of the enum, not its name (here: `?direction=UP`).

## Dates & timestamps

There are three parsers that give you a `Date` object, their difference is on how they encode the value into the query string.

### ISO 8601 Datetime

    import { parseAsIsoDateTime } from 'nuqs'

<empty query>

UTC

NowClear

### ISO 8601 Date

    import { parseAsIsoDate } from 'nuqs'

<empty query>

UTC

NowClear

The Date is parsed without the time zone offset, making it at 00:00:00 UTC.

  
_Support: introduced in version 2.1.0._

### Timestamp

Miliseconds since the Unix epoch.

    import { parseAsTimestamp } from 'nuqs'

<empty query>

UTC

NowClear

## Arrays

All of the parsers on this page can be used to parse arrays of their respective types.

    import { parseAsArrayOf, parseAsInteger } from 'nuqs'   parseAsArrayOf(parseAsInteger)   // Optionally, customise the separator parseAsArrayOf(parseAsInteger, ';')

## JSON

If primitive types are not enough, you can encode JSON in the query string.

Pass it a validation function to validate and infer the type of the parsed data, like a Zod schema:

    import { parseAsJson } from 'nuqs' import { z } from 'zod'   const schema = z.object({  pkg: z.string(),  version: z.number(),  worksWith: z.array(z.string()) })   // This parser is a function, don't forget to call it with the parse function // as an argument. const [json, setJson] = useQueryState('json', parseAsJson(schema.parse))   setJson({  pkg: 'nuqs',  version: 2,  worksWith: ['Next.js', 'React', 'Remix', 'React Router', 'and more'] })

<empty query>

null

Try itClear

Using other validation libraries is possible, as long as they throw an error when the data is invalid (eg: Valibot, Yup, etc).

## Using parsers server-side

For shared code that may be imported in the Next.js app router, you should import parsers from `nuqs/server` to use them in both server & client code, as it doesn’t include the `'use client'` directive.

    import { parseAsString } from 'nuqs/server'

Importing from `nuqs` will only work in client code, and will throw bundling errors when using functions (like `.withDefault` & `.withOptions`) across shared code.

For all other frameworks, you can use either interchangeably, as they don’t care about the `'use client'` directive.

Previous

Basic usage

Next

Custom parsers

---

## Page: https://nuqs.47ng.com/docs/parsers/making-your-own

Parsers

# Custom parsers

Making your own parsers for custom data types & pretty URLs

You may wish to customise the rendered query string for your data type. For this, `nuqs` exposes the `createParser` function to make your own parsers.

You pass it two functions:

1.  `parse`: a function that takes a string and returns the parsed value, or `null` if invalid.
2.  `serialize`: a function that takes the parsed value and returns a string.

    import { createParser } from 'nuqs'   const parseAsStarRating = createParser({  parse(queryValue) {  const inBetween = queryValue.split('★')  const isValid = inBetween.length > 1 && inBetween.every(s => s === '')  if (!isValid) return null  const numStars = inBetween.length - 1  return Math.min(5, numStars)  },  serialize(value) {  return Array.from({length: value}, () => '★').join('')  } })

<empty query>

Clear

## Caveat: lossy serializers

If your serializer loses precision or doesn’t accurately represent the underlying state value, you will lose this precision when reloading the page or restoring state from the URL (eg: on navigation).

Example:

    const geoCoordParser = {  parse: parseFloat,  serialize: v => v.toFixed(4) // Loses precision }   const [lat, setLat] = useQueryState('lat', geoCoordParser)

Here, setting a latitude of 1.23456789 will render a URL query string of `lat=1.2345`, while the internal `lat` state will be correctly set to 1.23456789.

Upon reloading the page, the state will be incorrectly set to 1.2345.

Previous

Built-in parsers

Next

TanStack Table Parsers

---

## Page: https://nuqs.47ng.com/docs/parsers/community/tanstack-table

ParsersCommunity

# TanStack Table Parsers

Store your table state in the URL, with style.

TanStack Table is a popular library for managing tabular content in React (and other frameworks).

By default, it will store its state in memory, losing all filters, sorts and pagination when the page is refreshed. This is a prime example where URL state shines.

## Pagination

TanStack Table stores pagination under two pieces of state:

*   `pageIndex`: a zero-based integer representing the current page
*   `pageSize`: an integer representing the number of items per page

You will likely want the URL to follow your UI and be one-based for the page index:

*   Previous
*   1
*   2
*   3
*   4
*   5
*   Next

Items per page10

Configure and copy-paste this parser into your application:

search-params.pagination.ts

    import {  parseAsIndex,  parseAsInteger,  parseAsString,  useQueryStates } from 'nuqs'  const paginationParsers = {  pageIndex: parseAsIndex.withDefault(0),  pageSize: parseAsInteger.withDefault(10) } const paginationUrlKeys = {  pageIndex: 'page',  pageSize: 'perPage' }  export function usePaginationSearchParams() {  return useQueryStates(paginationParsers, {  urlKeys: paginationUrlKeys  }) }

?page\=1&perPage\=10

Internal state

    {  // zero-indexed  pageIndex: 0,  pageSize: 10 }

Page index URL key

Page size URL key

## Filtering

This section is empty for now, contributions are welcome!

## Sorting

This section is empty for now, contributions are welcome!

Previous

Custom parsers

Next

Options