Search Params
Bind Vue state to URL search params with useSearchParams.
useSearchParams binds state to URL search params via the History API, with no
router required. The URL is the single source of truth: refreshing, sharing,
or bookmarking the link restores the exact state, and updates preserve the
URL hash and any params managed by other code.
<script setup lang="ts">
import { } from 'kvantjs/vue'
import * as from 'kvantjs/schema'
const = ('q', .().(''))
</script>
<template>
< v-model="">
</template>Setting a key to undefined removes its entry. Values equal to the
schema default are never written. Defaults stay internal.
Multiple composables bound to the same key stay in sync automatically.
Key maps work too:
const = ({
: .().(''),
: .().(0),
: .(['asc', 'desc']).('asc'),
: .(.()).([]), // repeated params: ?tags=a&tags=b
})
. = { ...., : .. + 1 }
.. += 1 // deeply reactive!Fast-changing values
kvant does not yet provide built-in throttle/debounce for URL writes. Until then, avoid binding state directly to quickly changing values (text inputs, sliders), or wrap the binding in a throttled layer with local state:
<script setup lang="ts">
import { watchThrottled } from '@vueuse/core'
const search = useSearchParams('q', kv.string().default(''))
// Local ref updates instantly; the URL follows at most every 300 ms
const text = ref(search.value)
watchThrottled(text, v => search.value = v, { throttle: 300 })
</script>
<template>
<input v-model="text">
</template>Options
Prop
Type
Set options once for a component subtree using the provide function:
<script setup lang="ts">
import { } from 'kvantjs/vue'
({ : 'push' })
</script>Custom search serializer
The default serializer uses URLSearchParams, so values are flat strings
(or repeated keys for arrays). For nested structures, plug in a custom
parser/serializer, for example qs, by
defining your own binding (see Advanced Usage):
import { } from 'kvantjs'
import { } from 'kvantjs/vue'
import qs from 'qs'
export const {
: ,
:
} = (
(, ) => (, {
: => qs.(, { : true }),
: => qs.(, { : true }),
...,
}),
)With qs handling (de)serialization, the full power of kvantjs/schema
opens up inside the URL: objects, nested arrays, and more.
const = (
'filters',
.({
: .(.()).([]),
: .([.(), .()]).(),
}).({}),
)
// URL: ?filters[tags][0]=a&filters[tags][1]=b&filters[range][0]=1&filters[range][1]=9