Quick start

Prerequisite

This assumes an adapter is provided near the root of your app. Without one, the composables below throw.

One param

useQueryState binds a single query key to a writable ref. Pass the key and a codec describing its type:

<script setup lang="ts">
import { codecs, useQueryState } from '@vuqs/core'

const search = useQueryState('q', codecs.string.withDefault(''))
//    ^? QueryStateRef<string>
</script>

<template>
  <input v-model="search" placeholder="Search…">
  <p>You searched: {{ search }}</p>
</template>

The ref is an ordinary Vue ref bound to the q key, so v-model, computed, and watch all work. v-model writes the ref, and the ref writes the URL.

.withDefault('') does two things: it makes the ref non-nullable, and it keeps the default out of the URL.

URL	search
/	'' (the default)
/?q=	''
/?q=vue	'vue'

A group of params

Most filter UIs have several keys that change together. useQueryStates binds a whole group and returns a reactive values map plus batch writers. Each entry is a codec, with the map key used as the query key:

<script setup lang="ts">
import { codecs, useQueryStates } from '@vuqs/core'

const { values, clear } = useQueryStates({
  q: codecs.string.withDefault(''),
  sort: codecs.literal(['asc', 'desc'] as const).withDefault('asc'),
  page: codecs.integer.withDefault(1),
})
</script>

<template>
  <input v-model="values.q" placeholder="Search…">

  <select v-model="values.sort">
    <option value="asc">Ascending</option>
    <option value="desc">Descending</option>
  </select>

  <button @click="values.page++">Next page</button>
  <button @click="clear()">Reset filters</button>
</template>

Assigning several values.* in a row coalesces into one navigation, so a "reset everything" button writes the URL once, not three times.

TIP

values is a reactive map. To work with params as individual refs, convert it with toQueryRefs.

Next steps

• Concepts: the mental model behind codecs, params, and the commit cycle.
• Built-in codecs: every type vuqs ships, and how to build your own.
• Navigation & options: push vs replace, throttling, and option precedence.
• Modules: opt-in behavior composed onto useQueryStates when URL state alone is not enough.