Guide

Single values

Bind one query-string key to a typed, checked, writable ref with useQueryState.

useQueryState(key, codec) binds one key. It returns a WritableComputedRef: read it, assign it, or pass it to v-model.

/guide/single-value
numberCodec 0..10
booleanCodec
enumCodec
arrayCodec
{
  "count": 0,
  "compact": false,
  "view": "list",
  "tags": []
}
Each control is one useQueryState with a different codec.
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.

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