Built-in parsers

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'

Demo loading...

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

Demo loading...

Floating point

Same as integer, but uses parseFloat under the hood.

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

Demo loading...

Hexadecimal

Encodes integers in hexadecimal.

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

Demo loading...

Going further

Check out the Hex Colors playground for a demo.

Boolean

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

Demo loading...

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'

Demo loading...

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'

ISO 8601 Date

import { parseAsIsoDate } from 'nuqs'

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'

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

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

You may import parsers from nuqs/server to use them in your server code, as it doesn’t include the 'use client' directive.

import { parseAsString } from 'nuqs/server'

Note

It used to be available under the alias import nuqs/parsers, which will be dropped in the next major version.

Built-in parsers

On this page