vue-qs

!vue-qs social

  

> Note: This library is currently in active development. APIs may change significantly between versions. Please use with caution and expect breaking changes.

📖 Documentation: https://iamsomraj.github.io/vue-qs/
🌏 中文文档: https://iamsomraj.github.io/vue-qs/zh/

Type‑safe, reactive URL query parameters for Vue 3. Inspired by nuqs (React) but built for the Vue Composition API.

✨ Features

- 🔄 Bidirectional Sync: URL parameters stay in sync with your reactive state
- 🎯 Type Safety: Full TypeScript support with type inference
- 🚀 Vue 3 Ready: Built for Vue 3 Composition API
- 🔧 Flexible: Works with or without Vue Router
- 🛡️ SSR Safe: Server-side rendering compatible
- 📦 Tree Shakeable: Only import what you need
- 🎨 Customizable: Built-in codecs + custom serialization support

🎯 Why vue-qs?

Keep UI state (page, filters, search text, sort, tabs) in the URL so users can:

- 🔄 Refresh and keep state
- 🔗 Share links with specific state
- ⬅️➡️ Use browser back/forward buttons

vue-qs gives you composables that feel like normal refs/reactive objects, but they automatically stay in sync with the URL query string.

📦 Installation

``bash
npm install vue-qs


or

pnpm add vue-qs

or

bun add vue-qs
`

Peer Dependencies:

- vue ^3.3.0 (required)
- vue-router ^4.2.0 (optional, for router integration)

🚀 Quick Start

$3

`vue



`

$3

`vue



`

🔗 Vue Router Integration

$3

`ts
// main.ts
import { createApp } from 'vue';
import { createVueQsPlugin, createVueRouterAdapter } from 'vue-qs';
import { router } from './router';
import App from './App.vue';

const app = createApp(App);

app.use(
createVueQsPlugin({
queryAdapter: createVueRouterAdapter(router),
})
);
app.use(router);
app.mount('#app');
`

$3

`vue

`

🔧 Codecs (Type Conversion)

Import ready‑made codecs for common types:

`ts
import {
stringCodec,
numberCodec,
booleanCodec,
dateISOCodec,
createArrayCodec,
createJsonCodec,
} from 'vue-qs';

// Basic types
const name = queryRef('name', {
defaultValue: '',
codec: stringCodec,
});

const page = queryRef('page', {
defaultValue: 1,
codec: numberCodec,
});

const isActive = queryRef('active', {
defaultValue: false,
codec: booleanCodec,
});

// Complex types
const tags = queryRef('tags', {
defaultValue: [] as string[],
codec: createArrayCodec(stringCodec),
});

const filters = queryRef('filters', {
defaultValue: { category: 'all', sort: 'name' },
codec: createJsonCodec<{ category: string; sort: string }>(),
});
`

⚙️ Configuration Options

$3

| Option | Type | Default | Description |
| ------------------- | ------------------------- | ------------- | -------------------------------------------- |
| defaultValue | T | - | Initial value if parameter is missing |
| codec | QueryCodec | stringCodec | Parser and serializer for the type |
| parse | QueryParser | - | Custom parser function (overrides codec) |
| serializeFunction | QuerySerializer | - | Custom serializer function (overrides codec) |
| shouldOmitDefault | boolean | true | Remove from URL when equal to default |
| isEqual | (a: T, b: T) => boolean | Object.is | Custom equality function |
| historyStrategy | 'replace' \| 'push' | 'replace' | Browser history update strategy |
| queryAdapter | QueryAdapter | - | Override default query adapter |

$3

`ts
const filters = queryRef('filters', {
defaultValue: { category: 'all', sort: 'name' },
codec: createJsonCodec<{ category: string; sort: string }>(),
isEqual: (a, b) => a.category === b.category && a.sort === b.sort,
});
`

🛡️ SSR Safety

vue-qs is SSR-safe. On the server, the composables use an internal cache until hydration, so you can render initial HTML safely without touching window.

📚 API Reference

$3

Creates a reactive ref that syncs with a URL query parameter.

`ts
function queryRef(parameterName: string, options?: QueryRefOptions): Ref;
`

$3

Creates a reactive object that syncs multiple URL query parameters.

`ts
function queryReactive(
parameterSchema: TSchema,
options?: QueryReactiveOptions
): ReactiveQueryState;
`

$3

Creates an adapter for browser History API (default).

`ts
function createHistoryAdapter(): QueryAdapter;
`

$3

Creates an adapter for Vue Router integration.

`ts
function createVueRouterAdapter(router: Router): QueryAdapter;
`

$3

`bash


Clone and install

git clone https://github.com/iamsomraj/vue-qs.git
cd vue-qs
bun install

Development

bun run dev # Watch mode
bun run test # Run tests
bun run typecheck # Type checking
bun run lint # Linting
bun run docs:dev # Documentation dev server
``

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

- Inspired by nuqs for React
- Built with Vue 3 Composition API
- TypeScript support powered by TypeScript