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
- 1Ada Lovelace
- 2Alan Turing
- 3Grace Hopper
- 4Linus Torvalds
- 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
| Option | What it does |
|---|---|
schema | One codec per property, or a dynamicQueryState. Each property becomes a key of the value. |
prefix | Prepended to every key with a dot: prefix.key. |
urlKeys | URL keys that differ from the property names: { pageSize: 'size' }. |
historyMode | History mode for writes from this group. A codec's own historyMode wins for its key. |
rules | Cross-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.