Comparison
Against reading route.query by hand
route.query + router.replace | vue-route-query | |
|---|---|---|
| Value type | string | null | (string | null)[] | The codec's type, narrowed by the default |
| Invalid URL values | Your parsing code | Codec rules (min, max, int, enums, patterns) reject them, or clamp them; the default is used |
| Rules across keys | Your code | Named rules on useQueryStates |
| Default values in the URL | You remove them | Removed unless omitDefault: false |
| Two components writing in one tick | The second write can drop the first | Merged into one navigation |
| Back and forward | Watch the route yourself | Every bound ref updates |
| Keys known only at runtime | Your parsing code | dynamicQueryState |
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:
| nuqs | vue-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 |
urlKeys | urlKeys, 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.