Quick start
This page builds the list below in four steps. Its state is in the URL bar above it: search, pick a category, change page, then reload.
- piniastate
- vue-routerrouting
- nuxtrouting
- @vueuse/corestate
1. Bind one key
Start with the search box. useQueryState takes the URL key and a codec, and returns a writable ref. The codec says how to read the key, and what to use when it is missing.
const q = useQueryState('q', stringCodec({ default: '' }))
q.value = 'vue' // ?q=vue
q.value = '' // the key is removed: '' is the default
The ref works with v-model:
<template>
<UInput v-model="q" placeholder="Search packages" />
</template>
2. Type and check the other keys
The category is one of four strings, and the page is a whole number from 1. Pick the codec for each, with its rules:
const category = useQueryState('category', enumCodec(['state', 'routing', 'ui', 'tooling']))
category.value
const page = useQueryState('page', numberCodec({ default: 1, int: true, min: 1 }))
page.value
category has no default, so its type includes undefined, meaning "all categories". A hand-edited URL such as ?category=games or ?page=-3 breaks a rule, so the ref holds the default instead.
3. Group them
Search, category, and page change together: a new search should go back to page 1. Put them in one useQueryStates, so one assignment writes all of them in one navigation.
const filters = useQueryStates({
schema: {
q: stringCodec({ default: '', trim: true, maxLength: 40 }),
category: enumCodec(['state', 'routing', 'ui', 'tooling']),
page: numberCodec({ default: 1, int: true, min: 1 }),
},
})
function update(patch: Partial<typeof filters.value>) {
filters.value = { ...filters.value, page: 1, ...patch }
}
update({ q: 'vue' }) // ?q=vue, in one navigation
4. Read it like any ref
Everything downstream is plain Vue:
const pageSize = 4
const rows = computed(() => {
const { q, page } = filters.value return packages .filter((item) => item.name.includes(q))
.slice((page - 1) * pageSize, page * pageSize)
})
That is the whole component. The back button, a reload, and a shared link all restore it, and the server render already shows the right page.
Next
- Single values and grouped values in detail.
- Validation: rules, clamping, cross-field rules, and how to see what a link got wrong.
- Codecs: every codec and its options.