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 query updates notifying the server (to re-render Server Components on the app router and re-run getServerSideProps in the pages router), you can set shallow to false:

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

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

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

Clear on default

By default, when the state is set to the default value, the search parameter is not removed from the URL, and is reflected explicitly. This is because default values can change, and the meaning of the URL along with it.

If you want to remove the search parameter from the URL when it’s set to the default value, you can set clearOnDefault to true:

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

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