Codecs

Built-in codecs

Every codec, its URL format, and its options.

A codec is the boundary between the raw string in the URL and the typed value in your ref. Each one is a function: call it with options to set the default, the rules, and how the value writes.

CodecValueURL
stringCodec()string?name=emma
numberCodec()number?page=3
booleanCodec()boolean?open=true
enumCodec(['grid', 'table'])'grid' | 'table'?layout=grid
dateCodec({ format: 'date' })Date?from=2024-01-31
dateCodec({ format: 'datetime' })Date?at=2024-01-31T10:30:00.000Z
arrayCodec(item)item[]?tags=vue,nuxt
schemaCodec(schema)the schema's output?sort={"direction":"asc","key":"name"}

Edit the address bar of the demo to ?view=cards or ?count=42: the codec rejects the value and the ref holds the default.

/codecs/built-in-codecs
numberCodec 0..10
booleanCodec
enumCodec
arrayCodec
{
  "count": 0,
  "compact": false,
  "view": "list",
  "tags": []
}
Each control is one useQueryState with a different codec.

Options on every codec

OptionTypeDefaultWhat it does
defaultthe value typenoneUsed when the key is missing or rejected. Set it and undefined leaves the ref's type.
validate(value) => booleannoneA one-off rule, run after the built-in ones.
historyMode'push' | 'replace'the group's or client'sWhether a write that changes this key adds a history entry.
omitDefaultbooleantrueRemoves the key when the value equals the default.

stringCodec

OptionTypeWhat it does
trimbooleanTrims whitespace when reading.
minLength / maxLengthnumberRejects strings outside the length range.
patternRegExpRejects strings that do not match.
const 
sku
=
stringCodec
({
trim
: true,
pattern
: /^[A-Z]{3}-\d{4}$/ })

numberCodec

Rejects anything that is not a finite number, such as abc, an empty value, or Infinity.

OptionTypeWhat it does
intbooleanRejects numbers with a fraction.
min / maxnumberRejects numbers out of range, or clamps them.
outOfRange'reject' | 'clamp''reject' (default) uses the default; 'clamp' uses the nearest bound.
const 
pageSize
=
numberCodec
({
default
: 20,
int
: true,
min
: 10,
max
: 100,
outOfRange
: 'clamp' })
// ?pageSize=500 → 100

booleanCodec

Reads true and false. Anything else, such as 1 or yes, is rejected.

enumCodec

Keeps the literal types, so the ref is a union and not string. A default outside the list does not compile:

const 
sort
=
useQueryState
('sort',
enumCodec
(['newest', 'oldest', 'name'], {
default
: 'newest' }))
sort
.
value
= 'name'
sort.value = 'price'
Type '"price"' is not assignable to type '"newest" | "oldest" | "name"'.

dateCodec

format is required, because it decides what links look like. Days that do not exist, such as 2024-02-30, are rejected.

OptionTypeWhat it does
format'date' | 'datetime''date' writes 2024-01-31, read as UTC midnight: use it for calendar filters. 'datetime' writes a full ISO timestamp, and only accepts one with a timezone.
min / maxDateRejects dates out of range, or clamps them.
outOfRange'reject' | 'clamp'Same as numberCodec.

arrayCodec

Wraps an item codec. Each item goes through the item codec's format and rules.

OptionTypeWhat it does
separatorstringDefaults to ,. Pick another when items may contain commas.
minItems / maxItemsnumberRejects lists outside the size range.
uniquebooleanRemoves repeated items when reading.
invalidItems'reject' | 'drop''reject' (default): one bad item rejects the whole list, so a link never half-applies. 'drop': bad items are removed and reported in issues.
const 
status
=
arrayCodec
(
enumCodec
(['open', 'closed', 'draft']), {
default
: [],
invalidItems
: 'drop',
}) // ?status=open,bogus → ['open'] const
ids
=
arrayCodec
(
numberCodec
({
int
: true }), {
separator
: '|',
unique
: true })
// ?ids=4|8|8|15 → [4, 8, 15]

An empty list is removed from the URL when the default is empty. With a non-empty default it writes ?tags=, so the empty list survives a reload. Items that contain the separator are escaped, so ['a,b'] round-trips.

schemaCodec

For a whole object in one key. See Custom codecs.

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