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>
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>
Floating point
Same as integer, but uses parseFloat
under the hood.
import { parseAsFloat } from 'nuqs'
useQueryState('float', parseAsFloat.withDefault(0))
<empty query>
Hexadecimal
Encodes integers in hexadecimal.
import { parseAsHex } from 'nuqs'
useQueryState('hex', parseAsHex.withDefault(0x00))
<empty query>
Going further
Check out the Hex Colors playground for a demo.
Boolean
import { parseAsBoolean } from 'nuqs'
useQueryState('bool', parseAsBoolean.withDefault(false))
<empty query>
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>
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>
ISO 8601 Date
import { parseAsIsoDate } from 'nuqs'
<empty query>
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>
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
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.