Utilities

Serializer helper

To populate <Link> components with state values, you can use the createSerializer helper.

Pass it an object describing your search params, and it will give you a function to call with values, that generates a query string serialized as the hooks would do.

Example:

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

Base parameter

The returned serialize function can take a base parameter over which to append/amend the search params:

serialize('/path?baz=qux', { foo: 'bar' }) // /path?baz=qux&foo=bar
 
const search = new URLSearchParams('?baz=qux')
serialize(search, { foo: 'bar' }) // ?baz=qux&foo=bar
 
const url = new URL('https://example.com/path?baz=qux')
serialize(url, { foo: 'bar' }) // https://example.com/path?baz=qux&foo=bar
 
// Passing null removes existing values
serialize('?remove=me', { foo: 'bar', remove: null }) // ?foo=bar

Shorter search params keys

Just like useQueryStates, you can specify a urlKeys object to map the variable names defined by the parsers to shorter keys in the URL:

const serialize = createSerializer(
  {
    // 1. Use variable names that make sense for your domain/business logic
    latitude: parseAsFloat,
    longitude: parseAsFloat,
    zoomLevel: parseAsInteger
  },
  {
    // 2. Remap them to shorter keys in the URL
    urlKeys: {
      latitude: 'lat',
      longitude: 'lng',
      zoomLevel: 'z'
    }
  }
)
 
// 3. Use your variable names when calling the serializer,
// and the shorter keys will be rendered in the URL:
serialize({
  latitude: 45.18,
  longitude: 5.72,
  zoomLevel: 12
})
// ?lat=45.18&lng=5.72&z=12

Parser type inference

To access the underlying type returned by a parser, you can use the inferParserType type helper:

import { parseAsInteger, type inferParserType } from 'nuqs' // or 'nuqs/server'
 
const intNullable = parseAsInteger
const intNonNull = parseAsInteger.withDefault(0)
 
inferParserType<typeof intNullable> // number | null
inferParserType<typeof intNonNull> // number

For an object describing parsers (that you’d pass to createSearchParamsCache or to useQueryStates), inferParserType will return the type of the object with the parsers replaced by their inferred types:

import {
  parseAsBoolean,
  parseAsInteger,
  type inferParserType
} from 'nuqs' // or 'nuqs/server'
 
const parsers = {
  a: parseAsInteger,
  b: parseAsBoolean.withDefault(false)
}
 
inferParserType<typeof parsers>
// { a: number | null, b: boolean }

Serializer helper

Base parameter

Shorter search params keys

Parser type inference

On this page