Getting Started
Introduction
Typed URL query state for Vue and vue-router. Like ref(), but stored in the query string.
@chronicstone/vue-route-query binds query-string keys to writable refs. The value is parsed into a real type, written back to the URL when you assign it, and kept in step with the back and forward buttons.
Type in the box below, then reload the page or copy the link into another tab.
/getting-started/introduction
Hello, anonymous visitor!
Type, then reload the page or share the link.
const name = useQueryState('name', stringCodec({ default: '' }))
<template>
<UInput v-model="name" placeholder="Your name" />
<p>Hello, {{ name || 'anonymous visitor' }}!</p>
</template>
Why put state in the URL
Filters, tabs, sort orders, the page of a table, an open side panel: if a user would want it to survive a reload, or to send it to a colleague, it belongs in the URL. Keeping it there by hand means reading route.query strings, parsing them, writing them back with router.replace, and making sure two components writing at once do not overwrite each other.
This library does that part:
- Typed and checked. A codec turns the raw string into a
number,Date, a string union, an array, or your own type, and checks it:min,max,int, lengths, patterns. A value that breaks a rule falls back to the default. - Batched. Every write made in the same tick becomes one navigation, across all components.
- Grouped. Bind several keys to one object with
useQueryStates, under an optional prefix. - Cross-field rules. Declare that
fromcomes beforeto, and a link that breaks it loses only the key you name. See Validation. - Dynamic. Keys that only exist at runtime, such as user-defined filters, are supported with
dynamicQueryState. - Small. About 5 kB minified and gzipped, with
vueandvue-routeras its only peer dependencies. No validation library is bundled.
Where to go next
The API and the batching client are inspired by nuqs, which does this for React.