You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> This library is currently in active development. APIs may change significantly between versions. Please use with caution and expect breaking changes.
7
+
> **Note**: This library is currently in active development. APIs may change significantly between versions. Please use with caution and expect breaking changes.
- 🎨 **Customizable**: Built-in codecs + custom serialization support
23
+
24
+
## 🎯 Why vue-qs?
15
25
16
26
Keep UI state (page, filters, search text, sort, tabs) in the URL so users can:
17
27
18
-
- Refresh and keep state
19
-
- Share links
28
+
- 🔄 **Refresh and keep state**
29
+
- 🔗 **Share links with specific state**
30
+
- ⬅️➡️ **Use browser back/forward buttons**
20
31
21
-
vue-qs gives you small composables that feel like normal refs / reactive objects, but they stay in sync with the query string. You pick the type (string, number, boolean, Date, enum, arrays, custom) through codecs.
32
+
vue-qs gives you composables that feel like normal refs/reactive objects, but they automatically stay in sync with the URL query string.
22
33
23
-
## Install
34
+
## 📦 Installation
24
35
25
-
```sh
26
-
npm i vue-qs
36
+
```bash
37
+
npm install vue-qs
27
38
# or
28
39
pnpm add vue-qs
29
40
# or
30
41
bun add vue-qs
31
42
```
32
43
33
-
Peer dependency: vue ^3.3. Vue Router ^4.2 is optional (only if you want to integrate with router navigation).
44
+
**Peer Dependencies:**
45
+
46
+
-`vue` ^3.3.0 (required)
47
+
-`vue-router` ^4.2.0 (optional, for router integration)
48
+
49
+
## 🚀 Quick Start
34
50
35
-
##Quick start (no router)
51
+
### Basic Usage (No Router)
36
52
37
53
```vue
38
54
<script setup lang="ts">
39
55
import { queryRef } from 'vue-qs';
40
56
41
57
// Create a ref bound to ?name=...
42
-
// If the param is missing we fall back to the default ('').
43
-
const name = queryRef('name', { defaultValue: '', parse: String });
58
+
// Falls back to default value if param is missing
59
+
const name = queryRef('name', {
60
+
defaultValue: '',
61
+
});
44
62
</script>
45
63
46
64
<template>
47
65
<input v-model="name" placeholder="Your name" />
48
66
</template>
49
67
```
50
68
51
-
Multiple params in one reactive object:
69
+
### Multiple Parameters
52
70
53
71
```vue
54
72
<script setup lang="ts">
55
73
import { queryReactive } from 'vue-qs';
56
74
57
-
// Each field config controls parsing, defaults, omission rules
58
-
const { queryState } = queryReactive({
75
+
// Each field config controls parsing, defaults, and omission rules
By default if a value equals its `defaultValue`, the param is removed from the URL for cleanliness. Want it always there? Set `shouldOmitDefault: false`.
101
+
const app =createApp(App);
110
102
111
-
Call `.syncToUrl()` on a ref or the reactive group to force a write right now.
103
+
app.use(
104
+
createVueQsPlugin({
105
+
queryAdapter: createVueRouterAdapter(router),
106
+
})
107
+
);
108
+
app.use(router);
109
+
app.mount('#app');
110
+
```
112
111
113
-
##Codecs (parse + serialize)
112
+
### Option 2: Per-Component Adapter
114
113
115
-
Import ready‑made codecs:
114
+
```vue
115
+
<script setup lang="ts">
116
+
import { queryRef, createVueRouterAdapter } from 'vue-qs';
117
+
import { useRouter } from 'vue-router';
116
118
117
-
```ts
118
-
import { serializers } from'vue-qs';
119
+
const router = useRouter();
120
+
const adapter = createVueRouterAdapter(router);
119
121
120
-
const n =queryRef('n', { defaultValue: 0, parse: serializers.numberCodec.parse });
121
-
const b =queryRef('b', { defaultValue: false, parse: serializers.booleanCodec.parse });
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`.
172
200
173
-
- Creates adapter for browser History API (default choice).
201
+
## 📚 API Reference
174
202
175
-
createVueRouterAdapter(router)
203
+
### `queryRef(name, options)`
176
204
177
-
-Creates adapter for Vue Router (enables reacting to navigations).
205
+
Creates a reactive ref that syncs with a URL query parameter.
0 commit comments