Custom codecs
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 inissues.serialize(value)returns the string to write, ornullto remove the key.- A
parseorvalidatethat 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. Usez.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.