API: composables

Functions for binding query params to refs and configuring the adapter they read and write through.

useQueryState @vuqs/core

Binds a single query key to a writable ref.

const state = useQueryState(path, codec?, options?)
const state = useQueryState(param, options?)

Parameters

• path: string
  • The query key to bind. Use a dot-path ('filters.sort') for nested keys.
  • Pass either path (with an optional codec) or a pre-built param.
• codec?: Codec<T>
  • How the value parses and serializes. Defaults to codecs.string.
  • A codec built with .withDefault(v) narrows the ref to a non-nullable T and keeps the default out of the URL.
• param?: DefinedQueryParam<T>
  • A param from queryParam, passed in place of path + codec.
• options?: UseQueryStatesOptions
  • Per-instance navigation and write behavior. See UseQueryStatesOptions.
  • String shorthand only: pass { defaultValue: string } for a plain string key. defaultValue is string-only; for other types pass codecs.X.withDefault(...).

Returns

• state: UseQueryStateReturn<T>
  • A writable computed ref (QueryStateRef<T>) with a .use() for modules. T is non-nullable when the codec or param carries a default, otherwise T | undefined.
  • state.value: T
    • Read or write the value; v-model binds here. Assigning undefined clears a nullable param.
  • state.set(value, options?): void
    • Write with per-call navigation options.
  • state.clear(options?): void
    • Remove the key from the URL, reverting to its default.
  • state.use(module): UseQueryStateReturn<…>
    • Compose a single-param module onto the ref, merging its API and widening the type. Returns the same ref object.

Type signature

// With a codec
function useQueryState<T>(path: string, codec: CodecWithDefault<T>, options?: UseQueryStatesOptions): UseQueryStateReturn<T>
function useQueryState<T>(path: string, codec: Codec<T>, options?: UseQueryStatesOptions): UseQueryStateReturn<T | undefined>

// String shorthand (no codec)
function useQueryState(path: string, options: StringOptions & { defaultValue: string }): UseQueryStateReturn<string>
function useQueryState(path: string, options?: StringOptions): UseQueryStateReturn<string | undefined>

// With a pre-built param
function useQueryState<T>(param: DefinedQueryParamWithDefault<T>, options?: UseQueryStatesOptions): UseQueryStateReturn<T>
function useQueryState<T>(param: DefinedQueryParam<T>, options?: UseQueryStatesOptions): UseQueryStateReturn<T | undefined>

StringOptions is UseQueryStatesOptions with parse/serialize forbidden, so a codec routes to the codec overloads.

Example

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

.set / .clear aren't reachable in templates

Vue auto-unwraps a top-level ref in templates, so call them from a function in <script setup>. See the guide.

useQueryStates @vuqs/core

Binds a schema of params to a reactive value map plus batch writers.

const { values, patch, replace, clear } = useQueryStates(schema, options?)

Parameters

• schema: TSchema
  • A map of logical name to a codec (the map key becomes the query key) or a param from queryParam (for a custom key, object param, or modifier).
• options?: UseQueryStatesOptions
  • Per-instance navigation and write behavior, shared by every param in the schema. See UseQueryStatesOptions.

Returns

• values: { [K in keyof TSchema]: … }
  • A reactive, writable map. values.k is the value, not a ref. A param with a default reads as non-nullable, otherwise T | undefined.
  • Replace, don't mutate: assign a new array or object; in-place mutation does not navigate.
• patch(values, options?): void
  • Partial batch write applied as one atomic transaction. Per param: a value sets, null clears, undefined/absent skips. Other writes in the same window may share its navigation.
• replace(values, options?): void
  • Whole-state write applied as one atomic transaction. Sets the given params and clears every param absent or explicitly undefined. Both are clear signals, so it takes no null. Other writes in the same window may share its navigation.
• clear(options?): void
  • Reset every param to its default as one atomic transaction (replace({})).
• .use(module): QueryComposable<…>
  • Layer a module onto the composable, merging its API and widening the return type. See the .use() model.

The grouped values map drops the per-field .set/.clear that useQueryState gives a single param. Use toQueryRefs to create one ref per field.

Throws if two params declare the same query path, or if no adapter has been provided (see provideQueryAdapter).

Example

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

toQueryRefs @vuqs/core

Projects the composable into one writable ref per field. Use it to recover the per-field .set/.clear that the grouped values map drops, or to pass a single field around.

function toQueryRefs<TSchema>(query: QueryBindingSource<TSchema>): ToQueryRefs<TSchema>

Parameters

• query: QueryBindingSource<TSchema>
  • The useQueryStates composable. For read-only per-field refs over a module's selected/defaults map, use Vue's toRefs directly.

Returns

• refs: ToQueryRefs<TSchema>
  • One QueryStateRef per param, with writable .value plus .set/.clear. A param with a default reads as non-nullable, otherwise T | undefined. Assigning undefined clears.

toQueryRef @vuqs/core

Binds the whole schema to one writable ref, the singular counterpart to toQueryRefs: a plain snapshot on read, an exhaustive replace on write. Use it when the value is the complete state, such as a form model or an API request object.

function toQueryRef<TSchema>(query: QueryBindingSource<TSchema>): QueryRef<TSchema>

Parameters

• query: QueryBindingSource<TSchema>
  • The useQueryStates composable.

Returns

• ref: QueryRef<TSchema>
  • A writable ref over the whole object, plus .set(value, options?) and .clear(options?).
  • Reading yields a plain snapshot: absent params are omitted, defaulted params always appear. The snapshot keeps a stable reference while its content is unchanged, so a whole-object v-model does not churn identity.
  • Writing replaces the state: params not present in the assigned value are cleared, as are params explicitly set to undefined. Both are clear signals, so it takes no null.

Example

import { toQueryRef, useQueryStates } from '@vuqs/core'

const query = useQueryStates({ q: codecs.string, sort: codecs.string })
const filters = toQueryRef(query)

filters.value = { q: 'phone', sort: 'desc' } // set q + sort, clear the rest
filters.value = { ...filters.value, q: 'sale' } // keep the object, change q
filters.clear()

UseQueryStatesOptions @vuqs/core

Per-instance behavior for both composables. The query source and URL writer come from the adapter, never from here.

Properties

• history?: 'replace' | 'push'
  • Default 'replace'. Push a new history entry, or replace the current one.
• scroll?: boolean
  • Default adapter-defined. Forwarded to the adapter.
• throttleMs?: number
  • Default a microtask. Coalesce writes within this window into one navigation.
• clearOnDefault?: boolean
  • Default true. Drop a value from the URL when it equals its resolved default.

See Navigation & options for behavior and precedence.

queryParam @vuqs/core

Builds a reusable param. Returns a chainable builder that is itself a param and can be passed to a schema, useQueryState, or the serializer.

const param = queryParam(path, codec?)
const param = queryParam.object(children)

Parameters

• path: string
  • The query key the param owns.
• codec?: Codec<T>
  • The codec bound to path. With none, the param is a plain string; { defaultValue } is shorthand for a string with a default. A CodecWithDefault produces a defaulted param.

Returns

• builder: QueryParamBuilder<T> (or QueryParamBuilderWithDefault<T> when defaulted)
  • A DefinedQueryParam<T> with chainable modifiers, each returning a new builder:
    • .withDefault(v): sets the param's default.
    • .withEquality(eq): sets how values compare (drives clearOnDefault).
    • .keepOnDefault(): keeps a default-valued write in the URL.
    • .transform({ read, write, eq? }): maps the param to a different public shape.

queryParam.object composes a multi-key param from child params:

queryParam.object(children) // merge child params into one object value
queryParam.object(prefix, children) // prefix every child key
queryParam.object(prefix, param) // reuse a param under a prefix

See Defining params for paths, object params, and reusable schemas.

Example

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

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

defineQuerySchema @vuqs/core

Names a reusable schema, normalized so its type stays stable across composables and typeof derivations.

function defineQuerySchema<TSchema>(schema: TSchema): NormalizeQueryStateSchema<TSchema>

Parameters

• schema: TSchema
  • A map of logical name to a codec or a queryParam definition, the same input useQueryStates accepts.

Returns

• schema: NormalizeQueryStateSchema<TSchema>
  • The schema with codec-shorthand entries normalized to DefinedQueryParam. Pass it to useQueryStates or createSerializer, and derive value types with QueryStateValues<typeof schema>.

Example

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

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

provideQueryAdapter @vuqs/core

Provides a QueryAdapter to descendant components, so their composables resolve query/navigate automatically.

function provideQueryAdapter(adapter: QueryAdapter): void

Parameters

• adapter: QueryAdapter
  • The adapter to provide. Call from a component setup.

Example

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

provideQueryAdapter(createVueRouterAdapter())

installQueryAdapter @vuqs/core

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

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:

installQueryAdapter(nuxtApp.vueApp, createVueRouterAdapter())

useQueryAdapter @vuqs/core

Reads the adapter provided by an ancestor.

function useQueryAdapter(): QueryAdapter | undefined

Returns

• adapter: QueryAdapter | undefined
  • The provided QueryAdapter, or undefined when there is no injection context or no adapter. Safe to call outside a component.