You may wish to customise the rendered query string for your data type.
For this, nuqs exposes the createParser{:ts} function to make your own parsers.
Creating a parser
You pass createParser{:ts} two required functions:
parse{:ts}: a function that takes a string and returns the parsed value, or null{:ts} if invalid.serialize{:ts}: a function that takes the parsed value and returns a string.
import { createParser } from 'nuqs'
const parseAsStarRating = createParser({
parse(queryValue) {
const inBetween = queryValue.split('★')
const isValid = inBetween.length > 1 && inBetween.every(s => s === '')
if (!isValid) return null
const numStars = inBetween.length - 1
return Math.min(5, numStars)
},
serialize(value) {
return Array.from({length: value}, () => '★').join('')
}
})
// Usage:
const [rating, setRating] = useQueryState('rating', parseAsStarRating)
// URL: ?rating=★★★ (3 stars)
The parse{:ts} function should always return null{:ts} for invalid inputs.
Never throw an error from the parse function.
Hex color parser example
Here’s a practical example of a parser that handles hex color values:
import { createParser, parseAsHex } from 'nuqs'
// Wrapping your parser/serializer in `createParser`
// gives it access to the builder pattern & server-side
// parsing capabilities:
const hexColorSchema = createParser({
parse(query) {
if (query.length !== 6) {
return null // always return null for invalid inputs
}
return {
// When composing other parsers, they may return null too.
r: parseAsHex.parse(query.slice(0, 2)) ?? 0x00,
g: parseAsHex.parse(query.slice(2, 4)) ?? 0x00,
b: parseAsHex.parse(query.slice(4)) ?? 0x00
}
},
serialize({ r, g, b }) {
return (
parseAsHex.serialize(r) +
parseAsHex.serialize(g) +
parseAsHex.serialize(b)
)
}
})
// Eg: set common options directly
.withOptions({ history: 'push' })
// Or on usage:
const [color, setColor] = useQueryState(
'color',
hexColorSchema.withDefault({
r: 0x66,
g: 0x33,
b: 0x99
})
)
// URL: ?color=663399
Equality function
For state types that can’t be compared by the ==={:ts} operator, you’ll need to
provide an eq{:ts} function as well:
// Eg: TanStack Table sorting state
// /?sort=foo:asc → { id: 'foo', desc: false }
const parseAsSort = createParser({
parse(query) {
const [key = '', direction = ''] = query.split(':')
const desc = parseAsStringLiteral(['asc', 'desc']).parse(direction) ?? 'asc'
return {
id: key,
desc: desc === 'desc'
}
},
serialize(value) {
return `${value.id}:${value.desc ? 'desc' : 'asc'}`
},
eq(a, b) {
return a.id === b.id && a.desc === b.desc
}
})
clearOnDefault{:ts} option,
to check if the current value is equal to the default value.
Multi Parsers
The parsers we’ve seen until now are SingleParsers{:ts}: they operate on the first occurence of the
key in the URL, and give you a string value to parse when it’s available.
MultiParsers{:ts} work similar to SingleParsers{:ts}, except that they operate on arrays, to support key repetition:
?tag=type-safe&tag=url-state&tag=react
parse{:ts} takes an Array<string>{:ts}. It receives all matching values of the key it operates on, and returns the parsed value, or null{:ts} if invalid.serialize{:ts} takes the parsed value and returns an Array<string>{:ts}, where each item will be separately added to the URL.
You can then compose & reduce this array to form complex data types:
import { createMultiParser, createParser, parseAsInteger } from 'nuqs'
/**
* 100~200 <=> { gte: 100, lte: 200 }
* 150 <=> { eq: 150 }
*/
const parseAsFromTo = createParser({
parse: value => {
const [min = null, max = null] = value.split('~').map(parseAsInteger.parse)
if (min === null) return null
if (max === null) return { eq: min }
return { gte: min, lte: max }
},
serialize: value => {
return value.eq !== undefined ? String(value.eq) : `${value.gte}~${value.lte}`
}
})
/**
* foo:bar <=> { key: 'foo', value: 'bar' }
*/
const parseAsKeyValue = createParser({
parse: value => {
const [key, val] = value.split(':')
if (!key || !val) return null
return { key, value: val }
},
serialize: value => {
return `${value.key}:${value.value}`
}
})
const parseAsFilters = <TItem extends {}>(itemParser: SingleParser<TItem>) => {
return createMultiParser({
parse: values => {
const keyValue = values.map(parseAsKeyValue.parse).filter(v => v !== null)
const result = Object.fromEntries(
keyValue.flatMap(({ key, value }) => {
const parsedValue: TItem | null = itemParser.parse(value)
return parsedValue === null ? [] : [[key, parsedValue]]
})
)
return Object.keys(result).length === 0 ? null : result
},
serialize: values => {
return Object.entries(values).map(([key, value]) => {
if (!itemParser.serialize) return null
return parseAsKeyValue.serialize({ key, value: itemParser.serialize(value) })
}).filter(v => v !== null)
}
})
}
const [filters, setFilters] = useQueryState(
'filters',
parseAsFilters(parseAsFromTo).withDefault({})
)
// URL: ?filters=price:100~200&filters=rating:5
Builder pattern
Parsers created with createParser{:ts} have access to the builder pattern,
allowing you to chain configuration methods:
const myParser = createParser({
parse: (value) => /* ... */,
serialize: (value) => /* ... */
})
.withDefault(defaultValue)
.withOptions({
history: 'push',
shallow: false
})
Testing custom parsers
Parsers should be bijective: parse(serialize(x)) === x{:ts} and serialize(parse(x)) === x{:ts}.
To help test bijectivity, you can use helpers defined in nuqs/testing:
import {
isParserBijective,
testParseThenSerialize,
testSerializeThenParse
} from 'nuqs/testing'
it('is bijective', () => {
// Passing tests return true
expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true)
// Failing test throws an error
expect(() => isParserBijective(parseAsInteger, '42', 47)).toThrowError()
// You can also test either side separately:
expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true)
expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true)
// Those will also throw an error if the test fails,
// which makes it easier to isolate which side failed:
expect(() => testParseThenSerialize(parseAsInteger, 'not a number')).toThrowError()
expect(() => testSerializeThenParse(parseAsInteger, NaN)).toThrowError()
})
Lossy serializers
If your serializer loses precision or doesn’t accurately represent
the underlying state value, you will lose this precision when
reloading the page or restoring state from the URL (eg: on navigation).Example:const geoCoordParser = {
parse: parseFloat,
serialize: v => v.toFixed(4) // Loses precision
}
const [lat, setLat] = useQueryState('lat', geoCoordParser)
lat=1.2345, while the internal lat state will be correctly
set to 1.23456789.Upon reloading the page, the state will be incorrectly set to 1.2345.