Getting Started

Comparison

How vue-route-query compares with reading route.query by hand, VueUse's useRouteQuery, and nuqs.

Against reading route.query by hand

route.query + router.replacevue-route-query
Value typestring | null | (string | null)[]The codec's type, narrowed by the default
Invalid URL valuesYour parsing codeCodec rules (min, max, int, enums, patterns) reject them, or clamp them; the default is used
Rules across keysYour codeNamed rules on useQueryStates
Default values in the URLYou remove themRemoved unless omitDefault: false
Two components writing in one tickThe second write can drop the firstMerged into one navigation
Back and forwardWatch the route yourselfEvery bound ref updates
Keys known only at runtimeYour parsing codedynamicQueryState

Against VueUse useRouteQuery

useRouteQuery from @vueuse/router binds one key to a ref with an optional transform. It is a good fit for a single string or number.

vue-route-query adds what larger screens need: codecs with rules that serialize as well as parse, a typed group of keys behind one object with cross-field rules, runtime-defined keys, removal of default values, and one navigation for every write in the same tick.

Against nuqs

nuqs is the React library this one takes after: parsers, useQueryState, useQueryStates, and a batched URL writer. If you know nuqs, the mapping is direct:

nuqsvue-route-query
useQueryState('page', parseAsInteger.withDefault(1))useQueryState('page', numberCodec({ default: 1, int: true }))
useQueryStates({ ... })useQueryStates({ schema: { ... } })
parseAsStringLiteral([...])enumCodec([...])
parseAsArrayOf(parser)arrayCodec(codec)
parseAsJson(validator)schemaCodec(standardSchema)
createParser({ parse, serialize })defineCodec({ parse, serialize })
.withOptions({ history: 'push' })historyMode: 'push' in the codec options
urlKeysurlKeys, plus prefix

The main difference is validation. nuqs parsers read a format, and rules such as page >= 1 are written by hand in a custom parser. Here every codec takes its rules as options (min, max, int, outOfRange: 'clamp', lengths, pattern, validate), and useQueryStates takes named cross-field rules.

The return value is a Vue WritableComputedRef rather than a [value, setValue] tuple, so it works with v-model and computed.

Copyright © 2026 Cyprien Thao. Released under the MIT License.