Getting Started

Introduction

Typed URL query state for Vue and vue-router. Like ref(), but stored in the query string.

@chronicstone/vue-route-query binds query-string keys to writable refs. The value is parsed into a real type, written back to the URL when you assign it, and kept in step with the back and forward buttons.

Type in the box below, then reload the page or copy the link into another tab.

/getting-started/introduction

Hello, anonymous visitor!

Type, then reload the page or share the link.
const 
name
=
useQueryState
('name',
stringCodec
({
default
: '' }))
<template>
  <UInput v-model="name" placeholder="Your name" />
  <p>Hello, {{ name || 'anonymous visitor' }}!</p>
</template>

Why put state in the URL

Filters, tabs, sort orders, the page of a table, an open side panel: if a user would want it to survive a reload, or to send it to a colleague, it belongs in the URL. Keeping it there by hand means reading route.query strings, parsing them, writing them back with router.replace, and making sure two components writing at once do not overwrite each other.

This library does that part:

  • Typed and checked. A codec turns the raw string into a number, Date, a string union, an array, or your own type, and checks it: min, max, int, lengths, patterns. A value that breaks a rule falls back to the default.
  • Batched. Every write made in the same tick becomes one navigation, across all components.
  • Grouped. Bind several keys to one object with useQueryStates, under an optional prefix.
  • Cross-field rules. Declare that from comes before to, and a link that breaks it loses only the key you name. See Validation.
  • Dynamic. Keys that only exist at runtime, such as user-defined filters, are supported with dynamicQueryState.
  • Small. About 5 kB minified and gzipped, with vue and vue-router as its only peer dependencies. No validation library is bundled.

Where to go next

Installation

Requirements, package managers, and Nuxt auto-imports.

Quick start

Build a searchable, paginated list whose state lives in the URL.

Codecs

Every built-in codec, and how to write your own.

Coming from v1

useRouteQuery and Zod schemas, mapped to the v2 API.
The API and the batching client are inspired by nuqs, which does this for React.
Copyright © 2026 Cyprien Thao. Released under the MIT License.