vuqsType-safe query state for Vue.

The URL is the single source of truth for view state. Typed, reactive, and bound to your router.

Get started

Why vuqs?

View on GitHub

🔗

The URL is your state

Bind query params to typed, reactive refs. One source of truth for view state, with no separate ref to keep in sync.

🧬

Codecs, not strings

A codec pairs parse with serialize as one unit, so a value and its URL form never drift. Rich built-ins cover the common types, or build your own.

🪝

Reactive by design

useQueryState returns a writable ref; useQueryStates returns a reactive map. v-model works, and concurrent writes coalesce into a single navigation.

🧭

Router-agnostic

The core knows nothing about your router. A tiny adapter plugs in vue-router, Nuxt, or anything that reads and writes a query.

🧩

Composable and extensible

Opt-in modules layer behavior onto your state with .use(). Tree-shakeable, so you pay only for what you import.

🧱

Build URLs, don't navigate

Turn values into a query string for links and redirects with the same schema, without binding to the router.

🧪

Testable

First-class testing utilities verify URL writes and codec round-trips without mounting a router.

🪶

Tiny and typed

Zero runtime dependencies, side-effect free, built for Vue, with full type inference.

Your state already lives in the URL

Search, filters, sort, and pagination belong in the query string, where a shared link restores the exact view. vuqs makes that state typed and reactive: you read values back as the types you declared, and write them like any ref.

vue

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

const search = useQueryState('q', codecs.string.withDefault(''))
const page = useQueryState('page', codecs.integer.withDefault(1))
</script>

<template>
  <input v-model="search" placeholder="Search…">
  <button @click="page++">Next page</button>
  <p>Searching “{{ search }}” on page {{ page }}</p>
</template>

Assigning a param writes the URL; the URL writes it back.

TIP

New here? Start with Installation, then read Concepts for the mental model.