Guide

Grouped values

Bind several keys to one typed object with useQueryStates, and write them in one navigation.

When several keys belong together, such as the page and page size of a table, bind them with useQueryStates. You get one ref holding one object, and assigning a new object writes every key in a single navigation.

/guide/grouped-values
  1. 1Ada Lovelace
  2. 2Alan Turing
  3. 3Grace Hopper
  4. 4Linus Torvalds
  5. 5Margaret Hamilton
1 / 5
Changing the page size also resets the page, in one navigation.
const 
pagination
=
useQueryStates
({
prefix
: 'users',
schema
: {
page
:
numberCodec
({
default
: 1,
int
: true,
min
: 1 }),
size
:
numberCodec
({
default
: 5,
int
: true,
min
: 5,
max
: 20,
outOfRange
: 'clamp' }),
}, }) function
setSize
(
size
: number) {
// Both keys change in one assignment, so the URL changes once.
pagination
.
value
= {
page
: 1,
size
}
}
pagination
.
value

Try ?users.size=500 in the address bar: the size is clamped to 20.

Options

OptionWhat it does
schemaOne codec per property, or a dynamicQueryState. Each property becomes a key of the value.
prefixPrepended to every key with a dot: prefix.key.
urlKeysURL keys that differ from the property names: { pageSize: 'size' }.
historyModeHistory mode for writes from this group. A codec's own historyMode wins for its key.
rulesCross-field rules, checked when the URL is read. See Validation.

Prefixes keep screens apart

Two tables on one screen can share one schema under different prefixes. Codecs describe values, not where they live, so the same schema object works for both:

const 
schema
= {
page
:
numberCodec
({
default
: 1,
int
: true,
min
: 1 }),
pageSize
:
numberCodec
({
default
: 20,
int
: true,
min
: 10,
max
: 100 }),
} const
users
=
useQueryStates
({
prefix
: 'users',
schema
,
urlKeys
: {
pageSize
: 'size' } })
const
teams
=
useQueryStates
({
prefix
: 'teams',
schema
,
urlKeys
: {
pageSize
: 'size' } })
// ?users.page=3&teams.page=2&teams.size=50

Write a whole object

The ref holds a plain object, so update it by assigning a new one. Mutating a property in place does not write to the URL:

pagination
.
value
= { ...
pagination
.
value
,
page
: 2 } // writes ?page=2
pagination
.
value
.
page
= 3 // does not write
To bind one property to v-model, wrap it in a computed with a getter and a setter that assigns the whole object.
Copyright © 2026 Cyprien Thao. Released under the MIT License.