Single values
useQueryState(key, codec) binds one key. It returns a WritableComputedRef: read it, assign it, or pass it to v-model.
{
"count": 0,
"compact": false,
"view": "list",
"tags": []
}const count = useQueryState('count', numberCodec({ default: 0, int: true, min: 0, max: 10 }))
const compact = useQueryState('compact', booleanCodec({ default: false }))
const view = useQueryState('view', enumCodec(['list', 'grid', 'board'], { default: 'list' }))
const tags = useQueryState(
'tags',
arrayCodec(enumCodec(['vue', 'nuxt', 'router', 'typescript']), {
default: [],
invalidItems: 'drop',
}),
)
view.value
Everything about the value lives in the codec call: its format, its rules, its default, and how it writes. The composable only says where it lives.
Defaults narrow the type
default decides whether undefined is part of the type. Give one and the ref never holds undefined:
const withDefault = useQueryState('layout', enumCodec(['grid', 'table'], { default: 'table' }))
withDefault.value
const withoutDefault = useQueryState('layout', enumCodec(['grid', 'table']))
withoutDefault.value
Defaults stay out of the URL
Writing the default value removes the key, so a fresh page has a clean URL and a shared link only carries what the user changed:
layout.value = 'grid' // ?layout=grid
layout.value = 'table' // key removed: it is the default
Pass omitDefault: false in the codec options to always write the key, for example when the default may change between releases and old links must keep their meaning.
Writes follow the same rules
A write goes through the codec before it is stored, so the ref never holds a value that a reload would reject:
const page = useQueryState('page', numberCodec({ default: 1, int: true, min: 1 }))
page.value = 0 // breaks min: 1, so the ref holds 1 and the key is removed
See Validation for every rule and what happens when one fails.
Several refs on one key
Two components can bind the same key. They share one cache, so a write from one updates the other in the same tick, before the URL changes.