Getting Started

Quick start

Build a searchable, paginated list whose search, category, and page live in the URL.

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.

/getting-started/quick-start
  • piniastate
  • vue-routerrouting
  • nuxtrouting
  • @vueuse/corestate
12 packages
1 / 3

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

Copyright © 2026 Cyprien Thao. Released under the MIT License.