Built-in codecs
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.
| Codec | Value | URL |
|---|---|---|
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.
{
"count": 0,
"compact": false,
"view": "list",
"tags": []
}Options on every codec
| Option | Type | Default | What it does |
|---|---|---|---|
default | the value type | none | Used when the key is missing or rejected. Set it and undefined leaves the ref's type. |
validate | (value) => boolean | none | A one-off rule, run after the built-in ones. |
historyMode | 'push' | 'replace' | the group's or client's | Whether a write that changes this key adds a history entry. |
omitDefault | boolean | true | Removes the key when the value equals the default. |
stringCodec
| Option | Type | What it does |
|---|---|---|
trim | boolean | Trims whitespace when reading. |
minLength / maxLength | number | Rejects strings outside the length range. |
pattern | RegExp | Rejects 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.
| Option | Type | What it does |
|---|---|---|
int | boolean | Rejects numbers with a fraction. |
min / max | number | Rejects 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'
dateCodec
format is required, because it decides what links look like. Days that do not exist, such as 2024-02-30, are rejected.
| Option | Type | What 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 / max | Date | Rejects 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.
| Option | Type | What it does |
|---|---|---|
separator | string | Defaults to ,. Pick another when items may contain commas. |
minItems / maxItems | number | Rejects lists outside the size range. |
unique | boolean | Removes 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.