vuqs

https://vuqs.dev
Admin
vuqs is a type-safe URL query state management library for Vue that synchronizes reactive state with...
Tokens:86,793
Snippets:713
Trust Score:2.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### installQueryAdapter example in Nuxt plugin

Source: https://vuqs.dev/api/composables

Example of installing an adapter app-wide, typically in a Nuxt plugin where no component instance is active.

```ts
installQueryAdapter(nuxtApp.vueApp, createVueRouterAdapter())
```

--------------------------------

### provideQueryAdapter example with vue-router

Source: https://vuqs.dev/api/composables

Example of providing a Vue Router adapter from a component setup.

```ts
import { provideQueryAdapter } from '@vuqs/core'
import { createVueRouterAdapter } from '@vuqs/core/adapters/vue-router'

provideQueryAdapter(createVueRouterAdapter())
```

--------------------------------

### createTestingAdapter usage example

Source: https://vuqs.dev/api/testing

Example showing how to create a testing adapter with initial search params, install it, and use useQueryState to read the query value.

```typescript
import { codecs, installQueryAdapter, useQueryState } from '@vuqs/core'
import { createTestingAdapter } from '@vuqs/core/adapters/testing'
import { createApp } from 'vue'

const adapter = createTestingAdapter({ searchParams: '?count=42' })
const app = createApp({})
installQueryAdapter(app, adapter)

const count = app.runWithContext(() => useQueryState('count', codecs.integer.withDefault(0)))
expect(count.value).toBe(42)
```

--------------------------------

### useQueryState example with codec

Source: https://vuqs.dev/api/composables

Example of using useQueryState with a codec that has a default. Shows reading and writing the value, pushing a history entry, and clearing back to the default. Note that .set and .clear are not reachable in templates; call them from a function in <script setup>.

```ts
import { codecs, useQueryState } from '@vuqs/core'

const page = useQueryState('page', codecs.integer.withDefault(1))

page.value++ // ?page=2
page.set(1, { history: 'push' }) // push a history entry
page.clear() // back to the default
```

--------------------------------

### queryParam example with codecs.literal

Source: https://vuqs.dev/api/composables

Example of building a reusable param with a literal codec and a default value.

```ts
import { codecs, queryParam } from '@vuqs/core'

const sort = queryParam('sort', codecs.literal(['asc', 'desc'] as const).withDefault('asc'))
```

--------------------------------

### createSerializer usage example with qs

Source: https://vuqs.dev/api/serializer

Example of creating a serializer with createSerializer, demonstrating basic serialization, patching over a base query, clearing a param, and using the stringify option to produce a query string.

```typescript
import { createSerializer } from '@vuqs/core'
import qs from 'qs'

const serialize = createSerializer(schema)
serialize({ q: 'phone' })                  // { q: 'phone' }
serialize(route.query, { page: 2 })        // patch over the current query
serialize(route.query, { currency: undefined }) // clear a param

const toUrl = createSerializer(schema, {
  stringify: q => qs.stringify(q, { addQueryPrefix: true }),
})
toUrl({ q: 'phone', page: 2 })             // '?q=phone&page=2'
```

--------------------------------

### Install @vuqs/core and @vuqs/nuxt with pnpm

Source: https://vuqs.dev/nuxt/getting-started

Run this command to add the required packages to your Nuxt project.

```bash
pnpm add @vuqs/core @vuqs/nuxt
```

--------------------------------

### Summary preset output examples

Source: https://vuqs.dev/guide/going-further/debugging

Example summary messages produced by the default `summary` preset. They show committed state changes, rollback explanations, external URL changes, and default-value handling.

```text
[vuqs] Updated the URL: "color" = "green".
```

```text
[vuqs] Could not update the URL; restored the previous value of "color".
```

```text
[vuqs] The URL changed outside vuqs; synchronized "color" and "page".
```

```text
[vuqs] "page" now uses its default value (1), so the URL does not need a "page" parameter.
```

--------------------------------

### Enable trace preset and example trace output

Source: https://vuqs.dev/guide/going-further/debugging

Enable the `trace` preset and an example trace message. The trace label includes the searchable event code; runtime, binding, transaction, batch, timestamps, and global sequence are in the details object.

```ts
enableDebug({ preset: 'trace' })
```

```text
[vuqs trace] gtq:enqueue — Queued 1 URL change; 1 path is now pending. { ... }
```

--------------------------------

### Calling .clear() from setup

Source: https://vuqs.dev/guide/essentials/use-query-state

Shows calling .clear() from a function in script setup because .set() and .clear() are not reachable in templates.

```vue
<script setup lang="ts">
const q = useQueryState('q', codecs.string.withDefault(''))

// Call .clear() from setup, where q is the real ref (not auto-unwrapped).
function clear() {
  q.clear()
}
</script>

<template>
  <input v-model="q">
  <button @click="clear()">Clear</button>
</template>
```

--------------------------------

### Install vue-router adapter in main.ts

Source: https://vuqs.dev/guide/getting-started/adapters

Installs the built-in vue-router adapter in `main.ts` after the router. Pass `router` explicitly because outside a component there is no `setup` to fall back to `useRouter()`. The adapter reads `router.currentRoute.value.query` and writes with `router.replace`, switching to `router.push` when the `history` option is `'push'`.

```ts
// main.ts
import { installQueryAdapter } from '@vuqs/core'
import { createVueRouterAdapter } from '@vuqs/core/adapters/vue-router'
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'

const app = createApp(App)

app.use(router)
installQueryAdapter(app, createVueRouterAdapter({ router }))

app.mount('#app')
```

--------------------------------

### Install @vuqs/core with bun

Source: https://vuqs.dev/guide/getting-started/installation

Adds @vuqs/core as a dependency using bun. vuqs is in active development; pin an exact version and review the changelog before upgrading.

```bash
bun add @vuqs/core
```

--------------------------------

### defineQuerySchema example

Source: https://vuqs.dev/api/composables

Example of defining a reusable schema with codec shorthand and a queryParam definition.

```ts
import { codecs, defineQuerySchema, queryParam } from '@vuqs/core'

export const filters = defineQuerySchema({
  q: codecs.string,
  status: queryParam('status', codecs.literal(['open', 'closed'] as const)),
})
```

--------------------------------

### installQueryAdapter

Source: https://vuqs.dev/api/composables

Installs a QueryAdapter app-wide on the Vue App instance, useful for Nuxt plugins.

```APIDOC
## installQueryAdapter

### Description
The app-level counterpart to `provideQueryAdapter`: provides the adapter on the Vue `App` rather than the current component instance.

### Signature
```ts
function installQueryAdapter(app: App, adapter: QueryAdapter): void
```

### Parameters
- `app: App` - The Vue application instance.
- `adapter: QueryAdapter` - The adapter to install app-wide.

### Example
Runs where there is no active component instance, most notably a Nuxt plugin, which is what the Nuxt module does:
```ts
installQueryAdapter(nuxtApp.vueApp, createVueRouterAdapter())
```
```

--------------------------------

### Install @vuqs/core with npm

Source: https://vuqs.dev/guide/getting-started/installation

Adds @vuqs/core as a dependency using npm. vuqs is in active development; pin an exact version and review the changelog before upgrading.

```bash
npm install @vuqs/core
```

--------------------------------

### Install @vuqs/core with yarn

Source: https://vuqs.dev/guide/getting-started/installation

Adds @vuqs/core as a dependency using yarn. vuqs is in active development; pin an exact version and review the changelog before upgrading.

```bash
yarn add @vuqs/core
```

--------------------------------

### provideBrowserHistoryAdapter usage example

Source: https://vuqs.dev/api/adapters

Provides a browser history adapter with default options that use replaceState for navigation. Call from a component setup in the browser; the adapter is disposed automatically when the effect scope stops.

```typescript
import { provideBrowserHistoryAdapter } from '@vuqs/core/adapters/browser-history'

provideBrowserHistoryAdapter({ defaultOptions: { history: 'replace' } })
```

--------------------------------

### Install @vuqs/core with pnpm

Source: https://vuqs.dev/guide/getting-started/installation

Adds @vuqs/core as a dependency using pnpm. vuqs is in active development; pin an exact version and review the changelog before upgrading.

```bash
pnpm add @vuqs/core
```

--------------------------------

### resetQueue usage example

Source: https://vuqs.dev/api/testing

Example of creating a testing adapter and calling resetQueue to discard a scheduled navigation. Use only when reusing an adapter.

```ts
import { createTestingAdapter } from '@vuqs/core/adapters/testing'

const adapter = createTestingAdapter()
// Schedule a write through a composable using adapter.
adapter.resetQueue()
```

--------------------------------

### withVuqsTestingAdapter usage example

Source: https://vuqs.dev/api/testing

Example usage of withVuqsTestingAdapter in a Vue Test Utils mount call. Passes options like searchParams to configure the adapter.

```ts
import { mount } from '@vue/test-utils'
import { withVuqsTestingAdapter } from '@vuqs/core/adapters/testing'

mount(MyComponent, {
  global: { plugins: [withVuqsTestingAdapter({ searchParams: '?count=42' })] },
})
```

--------------------------------

### isCodecBijective usage example

Source: https://vuqs.dev/api/testing

Example of using isCodecBijective with the integer codec. Shows a passing case and a failing case that throws.

```ts
import { isCodecBijective } from '@vuqs/core/testing'

expect(isCodecBijective(codecs.integer, '42', 42)).toBe(true)
expect(() => isCodecBijective(codecs.integer, '42', 47)).toThrow()
```

--------------------------------

### Use the module inline with .use

Source: https://vuqs.dev/modules/authoring

Shows how to consume the module with useQueryStates and useQueryState. The .use call pins the facade so the caller gets the matching option shape and autocomplete.

```typescript
useQueryStates(schema).use(withScope({ label: 'x', keys: ['q'] })) // grouped
useQueryState('q').use(withScope({ label: 'x', include: true })) // single
```

--------------------------------

### String output with stringify option

Source: https://vuqs.dev/guide/going-further/serializer

Shows how to configure the serializer to return a string instead of an object by passing a stringify function. The example uses qs.stringify with addQueryPrefix.

```TypeScript
import qs from 'qs'

const toUrl = createSerializer(schema, {
  stringify: query => qs.stringify(query, { addQueryPrefix: true }),
})

toUrl({ q: 'laptop', page: 2 }) // → '?q=laptop&page=2'
```

--------------------------------

### String base with parse option

Source: https://vuqs.dev/guide/going-further/serializer

Shows how to configure the serializer to accept a string base by passing a parse function. The example uses qs.parse and qs.stringify.

```TypeScript
const serialize = createSerializer(schema, {
  parse: search => qs.parse(search),
  stringify: query => qs.stringify(query),
})

serialize('q=old&page=5', { page: 1 }) // start from a string, return a string
```

--------------------------------

### withVuqsTestingAdapter

Source: https://vuqs.dev/api/testing

Returns a Vue plugin that builds a testing adapter and installs it on an app, for use with @vue/test-utils' global.plugins.

```APIDOC
## withVuqsTestingAdapter

### Description
Returns a Vue plugin that builds a testing adapter and installs it on an app, for use with `@vue/test-utils`' `global.plugins`.

### Signature
```ts
function withVuqsTestingAdapter(options?: TestingAdapterOptions): (app: App) => void
```

### Parameters
- **options** (`TestingAdapterOptions`) - Optional - The same options as `createTestingAdapter`.

### Returns
- **plugin** (`(app: App) => void`) - A Vue plugin. When you also need the adapter reference (to read `adapter.query.value`), call `createTestingAdapter` and install it yourself instead.

### Example
```ts
import { mount } from '@vue/test-utils'
import { withVuqsTestingAdapter } from '@vuqs/core/adapters/testing'

mount(MyComponent, {
  global: { plugins: [withVuqsTestingAdapter({ searchParams: '?count=42' })] },
})
```
```

--------------------------------

### Use withStorage on a single param with useQueryState

Source: https://vuqs.dev/modules/storage

Composes withStorage on a single query param. The example uses a key and a web storage adapter. Await search.storage.ready before using the storage.

```ts
import { codecs, useQueryState } from '@vuqs/core'
import { createWebStorage, withStorage } from '@vuqs/core/modules'

const search = useQueryState('q', codecs.string)
  .use(withStorage({
    key: 'catalog:search',
    storage: createWebStorage(() => window.localStorage),
  }))

await search.storage.ready
```

--------------------------------

### Grouped state example with useQueryStates

Source: https://vuqs.dev/guide/essentials/use-query-states

A complete Vue component using useQueryStates to manage query parameters for search, sort, and pagination. It demonstrates patch for atomic updates and clear to reset.

```Vue
<script setup lang="ts">
import { codecs, useQueryStates } from '@vuqs/core'
import { computed } from 'vue'

const { values, patch, clear } = useQueryStates({
  q: codecs.string.withDefault(''),
  sort: codecs.literal(['asc', 'desc'] as const).withDefault('asc'),
  page: codecs.integer.withDefault(1),
})

const results = computed(() => runSearch(values.q, values.sort, values.page))

function search(term: string) {
  // A new search resets to page 1, in one navigation.
  patch({ q: term, page: 1 })
}
</script>

<template>
  <input :value="values.q" @input="search(($event.target as HTMLInputElement).value)">
  <select v-model="values.sort">
    <option value="asc">Price ↑</option>
    <option value="desc">Price ↓</option>
  </select>

  <ul>
    <li v-for="r in results" :key="r.id">{{ r.name }}</li>
  </ul>

  <button @click="values.page++">Next page</button>
  <button @click="clear()">Reset</button>
</template>
```

--------------------------------

### Test composable with createTestingAdapter

Source: https://vuqs.dev/guide/going-further/testing

Creates a testing adapter with an in-memory ref, installs it on a throwaway app, and runs a composable in that app's injection context to read the initial query value.

```ts
import { codecs, installQueryAdapter, useQueryState } from '@vuqs/core'
import { createTestingAdapter } from '@vuqs/core/adapters/testing'
import { describe, expect, it } from 'vitest'
import { createApp } from 'vue'

it('reads the initial value', () => {
  const adapter = createTestingAdapter({ searchParams: '?count=42' })

  const app = createApp({})
  installQueryAdapter(app, adapter)

  const count = app.runWithContext(() => useQueryState('count', codecs.integer.withDefault(0)))

  expect(count.value).toBe(42)
})
```

--------------------------------

### Create a serializer with createSerializer and schema

Source: https://vuqs.dev/guide/going-further/serializer

Defines a schema with queryParam and codecs, then creates a serializer function. The example shows serializing an object with q and page, where page is converted to a string.

```TypeScript
import { codecs, createSerializer, queryParam } from '@vuqs/core'

const schema = {
  q: queryParam('q', codecs.string.withDefault('')),
  page: queryParam('page', codecs.integer.withDefault(1)),
  sort: queryParam('sort', codecs.literal(['asc', 'desc'] as const)),
}

const serialize = createSerializer(schema)

serialize({ q: 'laptop', page: 2 })
// → { q: 'laptop', page: '2' }
```

--------------------------------

### Composing a module with .use()

Source: https://vuqs.dev/guide/essentials/use-query-state

Composes a module onto a single ref with .use(). The module adds per-param API like setDefault and clearDefault. Call .use() synchronously during setup.

```ts
import { withRuntimeDefaults } from '@vuqs/core/modules'

const perPage = useQueryState('perPage', codecs.integer)
  .use(withRuntimeDefaults())

perPage.setDefault(20) // a runtime default, never written to the URL
perPage.value // reads through it: the selection if present, else 20
```

--------------------------------

### Use useQueryState with codecs.string in a Vue component

Source: https://vuqs.dev/nuxt/getting-started

After installation, composables and codecs are auto-imported. This example binds a query state to an input using the string codec with a default value.

```vue
<script setup lang="ts">
const search = useQueryState('q', codecs.string.withDefault(''))
</script>

<template>
  <input v-model="search">
</template>
```

--------------------------------

### codecs.literal usage example

Source: https://vuqs.dev/api/codecs

Usage example for codecs.literal with an as const array. The resulting QueryStateRef type is shown as 'asc' | 'desc' | undefined.

```ts
const sort = useQueryState('sort', codecs.literal(['asc', 'desc'] as const))
//    ^? QueryStateRef<'asc' | 'desc' | undefined>
```

--------------------------------

### Provide a custom adapter with query, navigate, and defaultOptions

Source: https://vuqs.dev/guide/getting-started/adapters

Use this snippet to create a custom adapter for Vuqs. It imports qs and provideQueryAdapter, then defines a navigate function that stringifies the query and uses history.pushState or replaceState based on options.history. The defaultOptions set history to 'replace'.

```typescript
import qs from 'qs'
import { provideQueryAdapter } from '@vuqs/core'

provideQueryAdapter({
  query: () => readQuerySomehow(),
  navigate: (query, options) => {
    const search = qs.stringify(query)
    if (options.history === 'push') {
      history.pushState(null, '', `?${search}`)
    }
    else {
      history.replaceState(null, '', `?${search}`)
    }
  },
  defaultOptions: { history: 'replace' },
})
```

--------------------------------

### Import codecs from @vuqs/core

Source: https://vuqs.dev/guide/codecs/built-in

Shows how to import the codecs object and use a ready-made codec or a factory to create a codec.

```typescript
import { codecs } from '@vuqs/core'

codecs.string // a ready-made codec
codecs.arrayOf(codecs.integer) // a factory: call it to get a codec
```

--------------------------------

### testSerializeThenParse usage example

Source: https://vuqs.dev/api/testing

Example of using testSerializeThenParse with the integer codec. Shows a passing case and a failing case with NaN that throws.

```ts
import { testSerializeThenParse } from '@vuqs/core/testing'

expect(testSerializeThenParse(codecs.integer, 42)).toBe(true)
expect(() => testSerializeThenParse(codecs.integer, Number.NaN)).toThrow()
```

--------------------------------

### testParseThenSerialize usage example

Source: https://vuqs.dev/api/testing

Example of using testParseThenSerialize with the integer codec. Shows a passing case and a failing case with a non-numeric string that throws.

```ts
import { testParseThenSerialize } from '@vuqs/core/testing'

expect(testParseThenSerialize(codecs.integer, '42')).toBe(true)
expect(() => testParseThenSerialize(codecs.integer, 'not-a-number')).toThrow()
```

--------------------------------

### createBrowserHistoryAdapter usage example

Source: https://vuqs.dev/api/adapters

Creates a browser history adapter and demonstrates navigation, external history updates, refresh, and disposal. The adapter writes with pushState when history: 'push' is passed, and preserves pathname, hash, and history.state. After disposal, navigation and refresh throw.

```typescript
import { createBrowserHistoryAdapter } from '@vuqs/core/adapters/browser-history'

const adapter = createBrowserHistoryAdapter()
adapter.navigate({ filters: { sort: 'name' }, tag: ['a', 'b'] }, { history: 'push' })
// ?filters.sort=name&tag=a&tag=b

window.history.replaceState(window.history.state, '', '?q=external')
adapter.refresh()
adapter.dispose()
```

--------------------------------

### codecs.enum usage example

Source: https://vuqs.dev/api/codecs

Usage example for codecs.enum with a TypeScript enum. It shows that the enum is passed directly and the resulting QueryStateRef type is Status | undefined.

```ts
enum Status {
  Active = 'active',
  Archived = 'archived',
}

const status = useQueryState('status', codecs.enum(Status))
//    ^? QueryStateRef<Status | undefined>
```

--------------------------------

### useQueryStates example

Source: https://vuqs.dev/api/composables

Shows how to use useQueryStates with codecs to manage multiple query parameters. The grouped values map drops per-field .set/.clear, so use patch for multiple updates and clear to reset all. Throws if two params declare the same query path or if no adapter is provided.

```typescript
import { codecs, useQueryStates } from '@vuqs/core'

const { values, patch, clear } = useQueryStates({
  q: codecs.string.withDefault(''),
  page: codecs.integer.withDefault(1),
})

values.q = 'laptop' // ?q=laptop
patch({ q: 'phone', page: 1 }) // one navigation
clear() // reset all
```

--------------------------------

### codecs.arrayOf usage example

Source: https://vuqs.dev/api/codecs

Usage example for codecs.arrayOf with codecs.string and withDefault([]). It shows that repeated query keys are collected into an array, e.g., ?tags=vue&tags=urls becomes ['vue', 'urls'].

```ts
const tags = useQueryState('tags', codecs.arrayOf(codecs.string).withDefault([]))
// ?tags=vue&tags=urls → ['vue', 'urls']
```

--------------------------------

### Example: active filter summary with withActiveParams

Source: https://vuqs.dev/modules/active-params

Example of using withActiveParams on a group to build a summary computed that reads activeCount and activeKeys. The exclude option removes 'page' from the active views.

```ts
import { codecs, useQueryStates } from '@vuqs/core'
import { withActiveParams } from '@vuqs/core/modules'
import { computed } from 'vue'

const filters = useQueryStates({
  q: codecs.string,
  category: codecs.string,
  sort: codecs.literal(['newest', 'price'] as const).withDefault('newest'),
  page: codecs.integer.withDefault(1),
}).use(withActiveParams({ exclude: ['page'] }))

const summary = computed(() => ({
  count: filters.activeCount.value,
  keys: filters.activeKeys.value,
}))
```

--------------------------------

### Using set and clear methods

Source: https://vuqs.dev/guide/essentials/use-query-state

Demonstrates reading/writing via .value, per-call options with .set, and removing the key with .clear.

```ts
q.value = 'laptop' // ?q=laptop
q.set('phone', { history: 'push' }) // push a history entry instead of replacing
q.clear() // back to '' and the key leaves the URL
```

--------------------------------

### useQueryStates with withContext and switchTo

Source: https://vuqs.dev/modules/context

Configures withContext on useQueryStates, providing active, preserve, and navigate. switchTo triggers one navigation with route and query reconciliation; per-call options like { history: 'push' } forward to navigate.

```ts
const { switchTo } = useQueryStates(schema)
  .use(withContext({
    active: () => route.params.tab as 'products' | 'orders',
    preserve: ['q'],
    navigate: (target, query) => router.push({ params: { tab: target }, query }),
  }))

switchTo('orders') // one navigation: new route + reconciled query
switchTo('orders', { history: 'push' }) // per-call options are forwarded to `navigate`
```

--------------------------------

### createBrowserHistoryAdapter

Source: https://vuqs.dev/api/adapters

Creates a BrowserHistoryAdapter that can be passed to installQueryAdapter or provideQueryAdapter. The adapter provides reactive query getter, navigate, refresh, and dispose methods.

```APIDOC
## createBrowserHistoryAdapter

### Description
Creates a BrowserHistoryAdapter ready to pass to `installQueryAdapter` or `provideQueryAdapter`. The adapter provides a reactive getter for the parsed URL query, a navigate method to update the URL, a refresh method to read external changes, and a dispose method to clean up.

### Method
Not applicable (function)

### Endpoint
Not applicable

### Parameters
- `options` (BrowserHistoryAdapterOptions) - Optional - The same options as `createBrowserHistoryAdapter`.

### Returns
- `BrowserHistoryAdapter` - The created adapter with the following methods:
  - `query`: a reactive getter for the parsed URL query.
  - `navigate`: synchronously writes with `replaceState`, or `pushState` for `history: 'push'`. Preserves the pathname, hash, and `history.state`. `scroll: true` scrolls to the top; otherwise the adapter leaves scroll in place.
  - `refresh()`: reads the current URL after external History API writes.
  - `dispose()`: removes the `popstate` listener and cancels pending writes. Repeated disposal is safe. Navigation and refresh throw after disposal.

### Example
```ts
import { createBrowserHistoryAdapter } from '@vuqs/core/adapters/browser-history'

const adapter = createBrowserHistoryAdapter()
adapter.navigate({ filters: { sort: 'name' }, tag: ['a', 'b'] }, { history: 'push' })
// ?filters.sort=name&tag=a&tag=b

window.history.replaceState(window.history.state, '', '?q=external')
adapter.refresh()
adapter.dispose()
```
```

--------------------------------

### transactions.observe

Source: https://vuqs.dev/modules/authoring

Observes transaction starts from the same adapter when raw query paths overlap the module schema.

```APIDOC
## transactions.observe

### Description
Registers an observer for transaction starts. Starts run synchronously in causal transaction id order, including writes triggered by synchronous reactive watchers. The snapshot is frozen and projected to the observer's local `keys`.

### Method
`observe`

### Signature
`observe({ start }) => () => void`

### Parameters
#### Observer Object
- **start** (function) - Required - Callback receiving a transaction object. The transaction has an `origin` property (symbol).

### Behavior
- A throwing observer is logged and isolated; it never aborts the producer or remaining observers.
- Register the returned disposer with `onScopeDispose`.

### Example
```ts
const origin = Symbol('my-module')
const stop = core.query.transactions.observe({
  start: transaction => {
    if (transaction.origin !== origin) {
      // React to an external write.
    }
  },
})

onScopeDispose(stop)
```
```

--------------------------------

### Built-in Codecs Summary

Source: https://vuqs.dev/guide/codecs/built-in

A summary of the built-in codecs provided by the library, including their types and URL examples.

```APIDOC
## Built-in Codecs Summary

### Codecs
| Codec | Type | URL example |
|---|---|---|
| `string` | `string` | `?q=laptop` |
| `integer` | `number` | `?page=2` |
| `float` | `number` | `?ratio=1.5` |
| `hex` | `number` | `?color=ff8800` |
| `index` | `number` (0-based) | `?page=1` → `0` |
| `boolean` | `boolean` | `?archived=true` |
| `literal([…])` | string union | `?sort=asc` |
| `numberLiteral([…])` | number union | `?perPage=20` |
| `enum(E)` | enum members | `?status=archived` |
| `isoDateTime` | `Date` | `?d=2026-06-22T10:00:00Z` |
| `isoDate` | `Date` | `?d=2026-06-22` |
| `timestamp` | `Date` | `?t=1719014400000` |
| `arrayOf(c)` | `T[]` | `?tags=a&tags=b` |
| `json({ validate? })` | `T` | `?f=%7B…%7D` |

For a type not covered here, build a custom codec.
```

--------------------------------

### Configure vuqs module in nuxt.config.ts

Source: https://vuqs.dev/nuxt/configuration

Example of configuring the vuqs module in nuxt.config.ts with autoImports and adapter options.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vuqs/nuxt'],
  vuqs: {
    autoImports: true,
    adapter: { defaultOptions: { history: 'replace' } },
  },
})
```

--------------------------------

### createTestingAdapter

Source: https://vuqs.dev/api/testing

Documentation for the createTestingAdapter function from @vuqs/core/adapters/testing.

```APIDOC
## createTestingAdapter

### Description
Builds a `QueryAdapter` backed by an in-memory ref, so a composable can run in tests without a router.

### Signature
```ts
function createTestingAdapter(options?: TestingAdapterOptions): TestingAdapter
```

### Parameters
- **options** (`TestingAdapterOptions`) - Optional
  - **searchParams** (`string | URLSearchParams | ParsedQuery`) - Optional - The initial query, default `{}`. A query string (with or without `?`), a `URLSearchParams`, or a query object. Dot-notation keys nest into objects the way the core resolves paths; repeated keys collapse into arrays.
  - **onUrlUpdate** (`OnUrlUpdateFunction`) - Optional - Invoked once per flushed navigation with the next query and resolved options. Several coalesced transactions produce one callback. Wire it to a spy to assert on URL changes.
  - **hasMemory** (`boolean`) - Optional - Default `false`. When `true`, each navigation updates `query` so later reads build on it. When `false`, `query` stays frozen at `searchParams` and each navigation is independent.
  - **defaultOptions** (`QueryAdapterDefaultOptions`) - Optional - App-wide defaults at the bottom of the precedence chain.

### Returns
- **adapter** (`TestingAdapter`) - A `QueryAdapter` whose `query` is exposed as a `Ref<ParsedQuery>`, so a test can read `adapter.query.value` to assert the URL state directly.
  - `resetQueue(): void` - Discards this adapter's pending optimistic writes and scheduled navigation. Fresh adapter instances are isolated automatically.
  - Pass it to `installQueryAdapter` or `provideQueryAdapter`.

### Example
```ts
import { codecs, installQueryAdapter, useQueryState } from '@vuqs/core'
import { createTestingAdapter } from '@vuqs/core/adapters/testing'
import { createApp } from 'vue'

const adapter = createTestingAdapter({ searchParams: '?count=42' })
const app = createApp({})
installQueryAdapter(app, adapter)

const count = app.runWithContext(() => useQueryState('count', codecs.integer.withDefault(0)))
expect(count.value).toBe(42)
```
```

--------------------------------

### createQueryStateEngine<TSchema>(options: QueryStateEngineOptions<TSchema>): QueryStateEngine<TSchema>

Source: https://vuqs.dev/api/serializer

Creates the reactive engine behind useQueryState and useQueryStates. It handles atomic transactions, adapter-scoped optimistic overlay, reconciliation, write coalescing, and navigation.

```APIDOC
## createQueryStateEngine<TSchema>(options: QueryStateEngineOptions<TSchema>): QueryStateEngine<TSchema>

### Description
Creates the reactive engine behind `useQueryState` and `useQueryStates`. It handles atomic transactions, adapter-scoped optimistic overlay, reconciliation, write coalescing, and navigation.

### Signature
```ts
function createQueryStateEngine<TSchema>(options: QueryStateEngineOptions<TSchema>): QueryStateEngine<TSchema>
```

### Parameters
- **options** (QueryStateEngineOptions<TSchema>) - Required - The schema, adapter, and resolved navigation, coalescing, and default behavior. See `QueryStateEngineOptions`.

### Returns
- **engine** (QueryStateEngine<TSchema>) - The reactive reads, defaults, transaction-based query I/O, resolved options, and pipeline facets a module receives.

### Remarks
Bindings using the same adapter share the optimistic overlay, write queue, and transaction-start registry. The engine is exposed for building higher layers and must run inside a Vue effect scope. See `QueryStateEngineOptions`.
```

--------------------------------

### query.transact

Source: https://vuqs.dev/modules/authoring

The only module write primitive. Applies a patch or replace to the optimistic state and emits a transaction start.

```APIDOC
## query.transact

### Description
Transacts a write to the query state. A `patch` preserves omitted params and clears explicit `undefined`; a `replace` clears absent or `undefined` entries. Both apply their full key set to the optimistic state before emitting one transaction start.

### Method
`transact`

### Signature
`transact: (request: QueryTransactionRequest<TSchema>) => void`

### Parameters
#### Request Body
- **mode** (`'patch' | 'replace'`) - Required - The transaction mode. `patch` preserves omitted params, `replace` clears absent or undefined entries.
- **values** (object) - Required - The values to apply.
- **origin** (symbol) - Optional - A symbol to identify the write origin; used to ignore own writes in observers.

### Behavior
- An empty patch creates no transaction.
- An explicitly touched key emits a start even when it serializes to a no-op.
- The complete request is validated and serialized before the optimistic overlay changes; unknown keys or codec/write-pipeline errors throw synchronously.
- The default policy is `'binding'`, applying `clearOnDefault`. Use `'preserve-explicit'` for exact selection replay.

### Example
```ts
const origin = Symbol('my-module')
core.query.transact({
  mode: 'patch',
  values: { page: 1 },
  origin,
})
```
```

--------------------------------

### withVuqsTestingAdapter signature

Source: https://vuqs.dev/api/testing

Signature for the Vue plugin factory. Returns a plugin that installs a testing adapter on an app for use with @vue/test-utils' global.plugins.

```ts
function withVuqsTestingAdapter(options?: TestingAdapterOptions): (app: App) => void
```

--------------------------------

### createQueryStateEngine

Source: https://vuqs.dev/api/types

Documentation for the createQueryStateEngine function and its returned types.

```APIDOC
## createQueryStateEngine

### Description
Creates a query state engine with the provided options. The engine exposes state, defaults, query, options, and pipeline facets.

### Method
createQueryStateEngine

### Parameters
#### Options
- **id** (string) - Required - Unique identifier for the engine.
- **schema** (TSchema) - Required - Schema for the query state.
- **adapter** (QueryAdapter) - Required - Adapter for the query state.
- **throttleMs** (number) - Optional - Throttle delay in milliseconds.
- **clearOnDefault** (boolean) - Optional - Whether to clear on default.
- **adapterClearOnDefault** (boolean) - Optional - Adapter-specific clear on default.

### Returns
- **state** (QueryStateReads<TSchema>) - Contains selected and values.
- **defaults** (QueryDefaultsBus<TSchema>) - Contains resolved and register.
- **query** (object) - Contains current, transact, and transactions.
- **options** (ResolvedQueryStateOptions) - Resolved options.
- **pipeline** (QueryPipelineBus) - Pipeline bus.

### Example
```ts
const engine = createQueryStateEngine({
  id: 'my-engine',
  schema: mySchema,
  adapter: myAdapter,
  throttleMs: 100,
  clearOnDefault: true,
  adapterClearOnDefault: false
});
```
```

--------------------------------

### Emit and react to a signal with core.hooks

Source: https://vuqs.dev/modules/signals

Shows how a module emits the 'context:change' signal with core.hooks.emit and how another module subscribes with core.hooks.on without importing the emitter. Handlers run synchronously in unspecified order and must be commutative; a throwing handler is isolated and logged.

```ts
// the emitting module
core.hooks.emit('context:change', nextContext)

// a reacting module, with no import of the emitter
const stop = core.hooks.on('context:change', () => { /* reset per-context state */ })
```

--------------------------------

### Codec.nullable example

Source: https://vuqs.dev/api/codecs

Shows using nullable with withDefault(null) on a string codec. Setting null removes the param and the state reads null.

```typescript
import { codecs, useQueryState } from '@vuqs/core'

const state = useQueryState('state', codecs.string.nullable().withDefault(null))
//    ^? QueryStateRef<string | null>

state.set('active')
state.set(null) // remove the param; state reads null
```

--------------------------------

### Import testing adapter and codec helpers

Source: https://vuqs.dev/guide/going-further/testing

Import the testing adapter and codec helpers from their dedicated subpaths to avoid pulling them into the app bundle.

```ts
import { createTestingAdapter, withVuqsTestingAdapter } from '@vuqs/core/adapters/testing'
import { isCodecBijective } from '@vuqs/core/testing'
```

--------------------------------

### Use withStorage with localStorage and query state

Source: https://vuqs.dev/modules/storage

Initializes query state with storage using a schema and a web storage adapter. Waits for storage readiness before using restored state, checks for errors, and flushes writes after patching values.

```ts
const query = useQueryStates(schema).use(withStorage({
  key: 'catalog:filters',
  storage: createWebStorage(() => window.localStorage),
}))

await query.storage.ready

if (query.storage.status.value === 'error') {
  reportStorageError(query.storage.error.value)
}

await loadProducts({ ...query.values })

query.patch({ q: 'phone' })
await query.storage.flush()
```
Tokens:
Raw