Codecs

Custom codecs

Write a codec for your own type with defineCodec, or store an object checked by Zod, Valibot, or ArkType.

defineCodec

defineCodec turns a URL format into a codec factory. The factory takes the same options as the built-in ones, so your codec gets default, validate, historyMode, and omitDefault for free:

const 
rangeCodec
=
defineCodec
<[number, number]>({
parse
(
raw
) {
const [
min
,
max
] =
raw
.
split
('..').
map
(
Number
)
return
min
!==
undefined
&&
max
!==
undefined
&&
Number
.
isFinite
(
min
) &&
Number
.
isFinite
(
max
)
? {
ok
: true,
value
: [
min
,
max
] }
: {
ok
: false,
issue
: {
reason
: 'format',
message
: 'expected min..max' } }
},
serialize
: ([
min
,
max
]) => `${
min
}..${
max
}`,
}) const
price
=
useQueryState
(
'price',
rangeCodec
({
default
: [0, 500],
validate
: ([
min
,
max
]) =>
min
<=
max
}),
) // ?price=10..200
price
.
value
  • parse(raw) gets the raw string, already URL-decoded. Return { ok: true, value }, or { ok: false, issue } to reject it. The issue's message shows up in issues.
  • serialize(value) returns the string to write, or null to remove the key.
  • A parse or validate that throws is caught and treated as a rejection.

Keep the two symmetric: parse(serialize(value)) should give back an equal value. That is what makes a shared link restore the same screen.

Objects backed by a schema

schemaCodec stores a whole object as JSON in one key, and checks it with any Standard Schema library: Zod, Valibot, or ArkType. The schema is both the type and the rule.

const 
sort
=
useQueryState
(
'sort',
schemaCodec
(
z
.
object
({
key
:
z
.
string
(),
direction
:
z
.
enum
(['asc', 'desc']) }), {
default
: {
key
: 'createdAt',
direction
: 'desc' },
}), ) // ?sort={"direction":"asc","key":"name"}
sort
.
value
.
direction
  • The package has no runtime dependency on any validation library. It calls the schema through the Standard Schema interface.
  • Schemas must be synchronous, because reading a ref is synchronous. An async schema is rejected with a clear issue.
  • Object keys are written in sorted order, so equal values always produce the same link, and a value equal to the default is removed from the URL whatever the order of its keys.
  • JSON has no dates: a z.date() field is written as an ISO string and then rejected. Use z.coerce.date() for date fields.

Choose the URL format

JSON keeps nested state in one key, at the cost of a long, encoded URL. Pass format to write something shorter. format.parse turns the raw string into the schema's input, and the schema still checks it; format.serialize writes the value:

const 
sort
=
useQueryState
(
'sort',
schemaCodec
(
z
.
object
({
key
:
z
.
string
(),
direction
:
z
.
enum
(['asc', 'desc']) }), {
default
: {
key
: 'createdAt',
direction
: 'desc' },
format
: {
parse
: (
raw
) => {
// The last `:` separates the direction, so a key may contain `:` itself. const
at
=
raw
.
lastIndexOf
(':')
return {
key
:
raw
.
slice
(0,
at
),
direction
:
raw
.
slice
(
at
+ 1) }
},
serialize
: ({
key
,
direction
}) => `${
key
}:${
direction
}`,
}, }), ) // ?sort=name:asc ?sort=name:up is rejected by the schema

format.serialize must write the same string for equal values: the default is removed from the URL by comparing those strings. A format.parse that throws is treated as a rejection. For flat filters, prefer one key per field with useQueryStates.

Copyright © 2026 Cyprien Thao. Released under the MIT License.