compare changes

vue-qs has a mascot: a friendly green ?, since every query string starts with one.

📖 Documentation

• Mascot as the favicon, nav logo and docs home hero image (en, zh), and a new 1280×640 social card used for the README banner and the docs OG image (5615f42)
• One tagline, "Type-safe search params state for Vue and Nuxt", across the README, docs and social card (5615f42)

compare changes

vue-qs now ships a Nuxt module: add modules: ['vue-qs/nuxt'] to nuxt.config and use useQueryState without any setup or imports.

🚀 Enhancements

• New vue-qs/nuxt module: installs the plugin with the Vue Router adapter and auto-imports useQueryState, useQueryStates and the parseAs* parsers; optional vueQs.defaultOptions and vueQs.autoImports (12feeb0)

📖 Documentation

• Nuxt module setup in the README, getting started, adapters guide and docs home page (en, zh) (12feeb0)

compare changes

vue-qs is now listed in Awesome Vue under State Management.

📖 Documentation

• Awesome Vue badge and mention in the README, and in the docs home page (en, zh) (da1a983)

compare changes

Brings vue-qs closer to nuqs: the nuqs parser, serializer, loader, Standard Schema and testing test suites now pass against vue-qs, except for vue-qs naming ([vue-qs] errors, the vue-qs Standard Schema vendor) and one deliberate difference: parser.parse returns null instead of throwing, so strict errors for throwing parsers say "got null".

🚀 Enhancements

• defaultOptions and processUrlSearchParams on createVueQs, provideQueryAdapter and <VueQsAdapter>, like nuqs adapters; createSerializer accepts processUrlSearchParams (a798ea5)
• New vue-qs/testing entry point with isParserBijective, testParseThenSerialize and testSerializeThenParse (44ebd66)
• Type names from nuqs: SingleParser, MultiParser, GenericParser, SingleParserBuilder, MultiParserBuilder, GenericParserBuilder, ParserWithOptionalDefault, LoaderFunction, LoaderFunctionOptions, SearchParams (44ebd66)

🩹 Fixes

• parseAsJson works with ArkType schemas (0bd9720)
• parseAsIsoDateTime / parseAsIsoDate reject impossible calendar dates, parseAsTimestamp rejects out-of-range timestamps, parseAsHex serializes negative numbers without padding (0bd9720)
• parseAsNativeArrayOf falls back to the default when no item is valid, and writes an empty array as ?key=; array parsers accept item parsers without serialize or eq (0bd9720)
• Parser keys named like Object.prototype members (constructor, hasOwnProperty) work in composables, urlKeys, createSerializer and createLoader (0f34047)
• createSerializer keeps credentials and empty hashes from URL bases (0f34047)
• createStandardSchemaV1 validates state values like nuqs: values are serialized, then parsed back in strict mode, so invalid values are reported as issues instead of falling back to defaults (0f34047)

⚠️ Behaviour changes

• createStandardSchemaV1 input is now state values keyed by state keys (not urlKeys). Strings still work for most parsers ({ page: '2' }), but not for parsers whose serialize expects a typed value, such as dates.
• Strict loader errors now read [vue-qs] Failed to parse query `abc` for key `page` (got null).

📖 Documentation

• App-wide settings in the adapters guide, testing custom parsers in the testing guide, and the parsers and server guides updated for the changes above

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

compare changes

📖 Documentation

• Add a runnable StackBlitz playground (Vite + Vue Router) linked from the README and docs (d7fecc3)
• Add a comparison page (vue-qs vs VueUse useRouteQuery vs route.query watchers) and a demo GIF in the README (a9927ee)
• Translate the Chinese guide to the 0.2 API: Getting Started, Parsers, Adapters and Migration (3ea6122)

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

compare changes

🏡 Chore

• Improve the npm package description and keywords so vue-qs is easier to find in npm search (bc62fc6)
• Add community health files: a Code of Conduct, issue forms and a Community section in the README and docs (c6b1d5d)

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

📣 Read the announcement and share feedback: #32

compare changes

🚀 Enhancements

• Support vue-router 5: the peer dependency range is now ^4.2.0 || ^5.0.0 (47aeebd)

🏡 Chore

• Upgrade the toolchain (Vitest 5, ESLint 10, TypeScript 6, vite 8, Bun 1.4 and others) and resolve all 68 known vulnerabilities in dev dependencies (bdbabf2)
• Deploy the docs with a GitHub Actions Pages workflow on release; the API reference is generated at build time (bdbabf2)
• CI: Node 22/24/26 matrix and the latest GitHub Actions (bdbabf2)

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

compare changes

🩹 Fixes

• Resync state after a rejected router navigation and skip no-op history updates (f6067b5)
  • Vue Router: when a navigation guard cancels or redirects an update, state now follows the resulting URL
  • History: history: 'push' no longer adds a duplicate entry when the URL does not change
  • Custom adapters can return false from updateUrl to signal a rejected update

📖 Documentation

• Unique page titles and descriptions, canonical URLs, Open Graph / Twitter images, sitemap, robots.txt, local search and a version menu (51e3a41)
• Regenerate the API reference with source links (7ae11cb)

🏡 Chore

• CI: format and publint checks, Node 20/22/24 matrix, and tests against the minimum peer versions (vue 3.3, vue-router 4.2) (51e3a41)
• Add SECURITY.md, a pull request template and Dependabot; update the issue templates, CONTRIBUTING.md and LICENSE; remove legacy config files (51e3a41)

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

compare changes

vue-qs is now a port of nuqs for Vue. See the migration guide.

⚠️ Breaking Changes

• Remove queryRef, queryReactive, createVueQsPlugin, the *Codec serializers and the URL utilities, replaced by the nuqs-style API below (#14)
• Adapters are imported from vue-qs/adapters/history and vue-qs/adapters/vue-router, and must be installed with createVueQs({ adapter }); composables throw when no adapter is provided
• Missing keys without a default are null instead of undefined; invalid values fall back to the default

🚀 Enhancements

• Add useQueryState, returning a writable ref (works with v-model) with a .set(value | updater | null, options) method returning a promise
• Add useQueryStates, returning a reactive object with $set and urlKeys support
• Add nuqs parsers: parseAsString, parseAsInteger, parseAsFloat, parseAsHex, parseAsIndex, parseAsBoolean, parseAsTimestamp, parseAsIsoDateTime, parseAsIsoDate, parseAsStringEnum, parseAsStringLiteral, parseAsNumberLiteral, parseAsArrayOf, parseAsNativeArrayOf, parseAsJson (validator or Standard Schema), createParser, createMultiParser, with .withDefault() and .withOptions()
• Add nuqs options: history, scroll, shallow, clearOnDefault (default true), limitUrlUpdates with throttle() / debounce()
• Batch updates made in the same tick into a single URL update
• Keep composables bound to the same key in sync
• Support repeated keys (?id=1&id=2)
• Add createLoader, createSerializer and createStandardSchemaV1, also available Vue-free from vue-qs/server
• Add the testing adapter (vue-qs/adapters/testing), createAdapter for custom adapters and the VueQsAdapter component
• Debug logging with localStorage.debug = 'vue-qs'

🩹 Fixes

• Vue Router adapter now follows every navigation (router.push, <RouterLink>), not only Back/Forward
• History adapter follows pushState / replaceState calls made by other code
• Update queues are scoped per adapter, so state no longer leaks between apps or SSR requests

📖 Documentation

• Rewrite the README and guides: parsers, options, adapters (including Nuxt), server utilities, testing, examples and migration from 0.1.x

✅ Tests

• Rewrite the test suite: parsers, serializer, loader, update queue, composables, History and Vue Router adapters, and type-level tests

❤️ Contributors

• Somraj Mukherjee (@iamsomraj)

compare changes

🚀 Enhancements

• Add isUpdating method to QueryAdapter and prevent infinite loops during URL updates (5c47647)
• Enhance package.json and README for clarity and usability (75960a4)

🩹 Fixes

• Update createEnumCodec to allow undefined values and adjust related tests (28d9815)

💅 Refactors

• Simplify queryReactive and queryRef APIs (d23e55e)
• Remove unit tests for vue-router adapter, query reactive, query ref, serializers, and core helpers (da5af50)
• Update import paths to use alias for better readability (c46bf58)

📖 Documentation

• Remove redundant active development notice from README (e4c5161)

🏡 Chore

• Update documentation for vue-qs v0.1.17 (03a7742)
• Update import paths in unit tests and standardize markdown separators (111de7c)
• Update version to 0.1.18-beta.7 and adjust documentation (bc37e2b)

✅ Tests

• Add comprehensive unit tests for serializers, Vue components, and Vue Router integration (8d1dd83)
• Add unit tests for serializers including string, number, boolean, date, JSON, array, and enum codecs (388f009)
• Add integration tests for BasicQueryRefComponent and QueryReactiveComponent with history and Vue Router support (560b507)

❤️ Contributors

• Iamsomraj (@iamsomraj)
• Somraj Mukherjee (@iamsomraj)