Getting Started
vue-qs is a type-safe search params state manager for Vue 3. It is a port of nuqs for Vue: the same parsers, options and behaviour, exposed through writable refs and reactive objects.
const page = useQueryState('page', parseAsInteger.withDefault(1));
page.value++; // ?page=2Try it online
Open the playground on StackBlitz: a Vite + Vue Router app with search, sort, pagination and tabs stored in the URL.
Installation
npm install vue-qspnpm add vue-qsbun add vue-qsRequires Vue 3.3+. vue-router (4.2+ or 5) is an optional peer dependency.
Install the plugin
vue-qs reads and writes the URL through an adapter. Install the plugin with the adapter that matches your app:
import { createApp } from 'vue';
import { createVueQs } from 'vue-qs';
import { createVueRouterAdapter } from 'vue-qs/adapters/vue-router';
import { router } from './router';
createApp(App)
.use(router)
.use(createVueQs({ adapter: createVueRouterAdapter(router) }))
.mount('#app');import { createApp } from 'vue';
import { createVueQs } from 'vue-qs';
import { createHistoryAdapter } from 'vue-qs/adapters/history';
createApp(App)
.use(createVueQs({ adapter: createHistoryAdapter() }))
.mount('#app');Using Nuxt? Add the module instead, which also auto-imports the composables and parsers:
// nuxt.config.ts
export default defineNuxtConfig({ modules: ['vue-qs/nuxt'] });See Adapters → Nuxt for options.
Your first query state
<script setup lang="ts">
import { useQueryState } from 'vue-qs';
const name = useQueryState('name'); // Ref<string | null>
</script>
<template>
<input v-model="name" placeholder="Your name" />
<p>Hello, {{ name || 'anonymous visitor' }}!</p>
<button @click="name = null">Clear</button>
</template>Typing in the input updates ?name=… in the URL, and navigating Back/Forward updates the input.
Typed state with parsers
Without a parser, state is a string | null. Pass a parser to get typed state, and .withDefault() to drop null:
import { parseAsBoolean, parseAsInteger, useQueryState } from 'vue-qs';
const page = useQueryState('page', parseAsInteger.withDefault(1)); // Ref<number>
const open = useQueryState('open', parseAsBoolean); // Ref<boolean | null>When the key is missing or its value is invalid, the state falls back to the default value. Setting the state to the default (or to null) removes the key from the URL.
Updating state
Assign .value, or call .set() to pass options or wait for the URL update:
page.value = 2;
await page.set((current) => current + 1); // updater function
await page.set(3, { history: 'push' }); // add a history entry
await page.set(null); // remove ?page (page.value === 1)
const search = await page.set(4); // URLSearchParams after the updateUpdates made in the same tick are batched into a single URL update.
Several keys at once
useQueryStates binds several keys to one reactive object:
<script setup lang="ts">
import { toRefs } from 'vue';
import { parseAsFloat, useQueryStates } from 'vue-qs';
const coordinates = useQueryStates({
lat: parseAsFloat.withDefault(45.18),
lng: parseAsFloat.withDefault(5.72),
});
const { lat, lng } = toRefs(coordinates); // writable refs, for v-model
function reset() {
coordinates.$set(null); // removes both keys in one update
}
</script>
<template>
<input v-model.number="lat" type="number" />
<input v-model.number="lng" type="number" />
</template>Next steps
- Parsers: every built-in parser and how to write your own
- Options: history, scroll, batching, throttle and debounce
- Adapters: Vue Router, Nuxt, plain History API, custom adapters
- Server:
createLoaderandcreateSerializer - Testing: unit-testing components that use vue-qs
- Migrating from 0.1.x
- Playground on StackBlitz: a runnable Vite + Vue Router example