Guide

Validation

Rules on each key, rules across keys, and what happens to a link that breaks them.

A URL is user input: people edit links, old links outlive your code, and anyone can paste anything. Every key goes through its codec's rules before your code sees it.

Rules on a key

Each codec takes the rules that make sense for its type, next to its default:

const 
filters
=
useQueryStates
({
schema
: {
search
:
stringCodec
({
trim
: true,
maxLength
: 80 }),
page
:
numberCodec
({
default
: 1,
int
: true,
min
: 1 }),
pageSize
:
numberCodec
({
default
: 20,
int
: true,
min
: 10,
max
: 100,
outOfRange
: 'clamp',
}),
salary
:
numberCodec
({
min
: 0,
validate
: (
amount
) =>
amount
% 1000 === 0 }),
from
:
dateCodec
({
format
: 'date',
min
: new
Date
('2020-01-01') }),
status
:
arrayCodec
(
enumCodec
(['open', 'closed', 'draft']), {
default
: [],
invalidItems
: 'drop',
}), }, })
CodecRules
stringCodectrim, minLength, maxLength, pattern
numberCodecint, min, max, outOfRange
dateCodecmin, max, outOfRange
enumCodecthe list of values
arrayCodecthe item codec's rules, minItems, maxItems, unique, invalidItems
every codec except schemaCodecvalidate: (value) => boolean for a one-off rule

What happens to a bad value

The URL holdsThe ref holds
No keyThe default, or undefined without one
A value in the wrong format (?page=abc)The default
A value that breaks a rule (?page=0 with min: 1)The default
A value out of range with outOfRange: 'clamp' (?pageSize=500)The nearest bound (100)
A list with one bad item (?status=open,bogus)The default, or the valid items with invalidItems: 'drop'

The URL is never rewritten on read. ?page=0 stays in the address bar until the next write to that key. Rewriting on read would turn a page load into a navigation, add or replace a history entry, and race with the user's own changes. The next write cleans the key anyway.

Writes follow the same rules. page.value = 0 stores 1 and removes the key; pageSize.value = 500 stores 100. The ref never holds a value a reload would reject.

Cross-field rules

Some rules span keys: a minimum below a maximum, a start date before an end date. Declare them on useQueryStates with a name, the keys they read, and the keys they reject:

const 
filters
=
useQueryStates
({
schema
: {
salaryMin
:
numberCodec
({
min
: 0 }),
salaryMax
:
numberCodec
({
min
: 0 }),
from
:
dateCodec
({
format
: 'date' }),
to
:
dateCodec
({
format
: 'date' }),
},
rules
: {
salaryRange
: {
keys
: ['salaryMin', 'salaryMax'],
check
: ({
salaryMin
,
salaryMax
}) =>
salaryMin
<=
salaryMax
,
reject
: ['salaryMax'],
message
: 'The maximum salary is below the minimum',
},
period
: {
keys
: ['from', 'to'],
check
: ({
from
,
to
}) =>
from
<=
to
,
reject
: ['to'],
}, }, }) // ?salaryMin=50000&salaryMax=40000 → salaryMin: 50000, salaryMax: undefined
  • check gets typed values, never undefined: a rule is skipped until every key it reads has a value.
  • When check returns false, only the keys in reject fall back to their defaults. The others keep their values.
  • Rules run in the order they are declared.
  • Rules run when the URL is read: on page load, on reload, on Back, and on a shared link. A write from your code is kept as it is, so a form never clears a field while the user is typing. Show the conflict from issues instead.

The client keeps a reactive map of every key whose URL value was rejected or only partly used, with the raw value, the reason, and partial: true when part of the value was kept (a list that dropped an item):

const 
client
=
useQueryStateClient
()
// { raw: '40000', reason: 'group', rule: 'salaryRange', message: '...' }
client
.
issues
.
get
('salaryMax')
const
invalidFilters
=
computed
(() => [...
client
.
issues
.
keys
()])

Use it to show "this link had invalid filters", or to point at the field. In development, each bad value is also logged once in the console.

reasonMeaning
formatNot a number, a date, a list member, or JSON.
optionA built-in rule rejected it (min, int, maxLength...).
validateThe codec's validate returned false, or a schemaCodec schema reported issues.
groupA cross-field rule rejected it. rule holds its name.
Copyright © 2026 Cyprien Thao. Released under the MIT License.