vue-qs 0.2: nuqs for Vue 🎉

[iamsomraj]

Hi everyone 👋

vue-qs 0.2 is out! It's a rewrite that makes vue-qs a port of nuqs, the popular type-safe search params library for React, built for Vue's way of doing things.

npm install vue-qs

Why the rewrite?

Filters, search terms, tabs and pagination belong in the URL: users can share them, bookmark them and restore them with the Back button. vue-qs 0.1 worked, but it had its own API and missed some important behaviour (for example, state didn't follow router.push). nuqs has already solved these problems well in React, so 0.2 follows its parsers, options and behaviour, and keeps the Vue feel.

<script setup lang="ts">
import { parseAsInteger, useQueryState } from 'vue-qs'

const search = useQueryState('q', { defaultValue: '' })              // Ref<string>
const page = useQueryState('page', parseAsInteger.withDefault(1))    // Ref<number>
</script>

<template>
  <input v-model="search" placeholder="Search…" />
  <button @click="page++">Next page</button>
</template>

Highlights

• ✍️ Writable refs: useQueryState returns a ref you can assign or bind with v-model, with .set() for options and promises
• 🧩 Reactive objects: useQueryStates binds several keys at once, with $set and short urlKeys
• 🔒 Type-safe parsers: integers, floats, booleans, dates, enums, literals, arrays, repeated keys, and parseAsJson validated with Zod / Valibot / ArkType (Standard Schema), plus createParser for your own
• 📦 Batched updates: changes made in the same tick produce one URL update
• ⏱️ Throttle and debounce: state stays instant, URL writes are rate-limited
• 🧭 Adapters: Vue Router 4 and 5, Nuxt, the plain History API, and an in-memory adapter for tests
• 🖥️ Server utilities: createLoader and createSerializer reuse your parsers in Nuxt server routes and for type-safe links

Since 0.2.0:

• 0.2.1: state now follows the URL when a navigation guard cancels or redirects an update, and the History adapter no longer adds duplicate history entries
• 0.2.2: vue-router 5 support, plus an upgraded toolchain with zero known vulnerabilities

Upgrading from 0.1

queryRef / queryReactive and the codecs are replaced by useQueryState / useQueryStates and parsers. The migration guide has a name-by-name mapping.

I'd love your feedback 💚

vue-qs is my way of giving back to the Vue community, and your input decides what comes next:

• 🙏 Questions → Q&A
• 💡 Ideas and API feedback → Ideas
• 🙌 Using it somewhere? → Show and tell
• 🛠️ Want to contribute? These are open: Chinese docs, a StackBlitz playground, a Nuxt module, and a Recipes page

Which feature would you like next? Reply below!

Big thanks to François Best and the nuqs contributors, whose work this port builds on.

📖 Docs · 📦 npm · 📝 Release notes