Options

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

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’s a no-op 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.

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

Rate-limiting 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 use a default throttle of 120ms (320ms for older versions of Safari).

This throttle time is configurable, and also allows you to debounce updates instead.

Throttle

If you want to increase the 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 limitUrlUpdates option:

useQueryState('foo', {
  // Send updates to the server maximum once every second
  shallow: false,
  limitUrlUpdates: {
    method: 'throttle',
    timeMs: 1000
  }
})
 
// or using the shorthand:
import { throttle } from 'nuqs'
 
useQueryState('foo', {
  shallow: false,
  limitUrlUpdates: throttle(1000)
})

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 throttle time 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.

Debounce

In addition to throttling, you can apply a debouncing mechanism to state updates, to delay the moment where the URL gets updated with the latest value.

This can be useful for high frequency state updates where you only care about the final value, not all the intermediary ones while typing in a search input or moving a slider.

We recommend you opt-in to debouncing on specific state updates, rather than defining it for the whole search param.

Let’s take the example of a search input. You’ll want to update it:

1. When the user is typing text, with debouncing
2. When the user clears the input, by sending an immediate update
3. When the user presses Enter, by sending an immediate update

You can see the debounce case is the outlier here, and actually conditioned on the set value, so we can specify it using the state updater function:

import { useQueryState, parseAsString, debounce } from 'nuqs';
 
function Search() {
  const [search, setSearch] = useQueryState(
    'q',
    parseAsString.withDefault('').withOptions({ shallow: false })
  )
 
  return (
    <input
      value={search}
      onChange={(e) =>
        setSearch(e.target.value, {
          // Send immediate update if resetting, otherwise debounce at 500ms
          limitUrlUpdates: e.target.value === '' ? undefined : debounce(500)
        })
      }
      onKeyPress={(e) => {
        if (e.key === 'Enter') {
          // Send immediate update
          setSearch(e.target.value)
        }
      }}
    />
  )
}

Resetting

You can use the defaultRateLimit import to reset debouncing or throttling to the default:

import { debounce, defaultRateLimit } from 'nuqs'
 
const [, setState] = useQueryState('foo', {
  limitUrlUpdates: debounce(1000)
})
 
// This state update isn't debounced
setState('bar', { limitUrlUpdates: defaultRateLimit })

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

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.

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

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