useQueryStates @vuqs/core

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

A query adapter must be provided in the current Vue injection context. The call throws when no adapter is available.

Usage

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

Type

function useQueryStates<TSchema extends QueryStateSchemaInput>(
  schema: TSchema,
  options?: UseQueryStatesOptions,
): QueryComposable<NormalizeQueryStateSchema<TSchema>>

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.

Return value

• query: QueryComposable<NormalizeQueryStateSchema<TSchema>>
  • The reactive values, batch writers, binding and module composition API.

Property	Description
values	Reactive, writable param values. Defaulted params read as T; others read as T | undefined. Replace arrays and objects to navigate; in-place mutations do not navigate.
patch(values, options?)	Partial atomic write. Omitted params are preserved; explicit undefined clears.
replace(values, options?)	Whole-state atomic write. Omitted or explicitly undefined params are cleared.
clear(options?)	Resets every param to its default as one atomic transaction.
binding	The schema-typed root used by toQueryRef and toQueryRefs.
use(module)	Composes a module. Returns the composable with the module's API and with values typed through the module's presence effects; capture the returned value.

Batch writes may share a navigation with other writes in the same scheduling window.

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).

UseQueryStatesOptions

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

interface UseQueryStatesOptions extends NavigateOptions {
  throttleMs?: number
  clearOnDefault?: boolean
}

Properties

Property	Type	Description
history	'replace' | 'push'	Optional. Defaults to 'replace'. Push or replace a history entry.
scroll	boolean | ScrollToOptions	Optional. Defaults to false. Where the window scrolls after navigation.
throttleMs	number	Optional. Defaults to a microtask. Coalesce writes within this many milliseconds.
clearOnDefault	boolean	Optional. Allows safe default omission. Falls back to the adapter setting, then true; param settings and per-call overrides take precedence.

See Navigation & options for behavior and precedence.

QueryStatesValues

type QueryStatesValues<TSchema extends QueryStateSchema> = {
  [Key in keyof TSchema]: QueryStateRefValue<TSchema[Key]>
}

QueryStatesActions

interface QueryStatesActions<TSchema extends QueryStateSchema> {
  patch: (values: QueryStateWriteValues<TSchema>, options?: QueryWriteOptions) => void
  replace: (values: QueryStateValues<TSchema>, options?: QueryWriteOptions) => void
  clear: (options?: QueryWriteOptions) => void
}

QueryWriteOptions

Options for one call to patch, replace, set or clear, including ref writers.

interface QueryWriteOptions extends NavigateOptions {
  clearOnDefault?: boolean
}

clearOnDefault overrides the param, composable and adapter settings for that write. Explicit clearing still removes the param regardless of this option. history and scroll follow NavigateOptions.

UseQueryStatesReturn

interface UseQueryStatesReturn<TSchema extends QueryStateSchema, TRead extends QueryReadShape<TSchema> = QueryReadMap<TSchema>>
  extends QueryStatesActions<TSchema>, QueryBindingSource<TSchema, TRead> {
  values: QueryStatesValues<TSchema, TRead>
}

type QueryReadMap<TSchema extends QueryStateSchema> = {
  [Key in keyof TSchema]: QueryStateRefValue<TSchema[Key]>
}

type QueryReadShape<TSchema extends QueryStateSchema> = { [Key in keyof TSchema]: unknown }

type QueryStatesValues<TSchema extends QueryStateSchema, TRead extends QueryReadShape<TSchema> = QueryReadMap<TSchema>> = {
  [Key in keyof TSchema]: TRead[Key]
}

TRead is the read value of each param. Without modules it is QueryReadMap, the base read contract. Assigning to values accepts the read type.

QueryComposable

type QueryComposable<
  TSchema extends QueryStateSchema,
  TApi extends object = object,
  TDescriptors extends readonly unknown[] = [],
> = UseQueryStatesReturn<TSchema, QueryReadOf<TSchema, TDescriptors>> & TApi & {
  use: <TModule extends QueryStatesUsable<TSchema>>(
    module: TModule & VerifiedStatesModule<TModule, TSchema>,
  ) => QueryComposable<
    TSchema,
    TApi & StatesModuleApi<TModule, TSchema>,
    [...TDescriptors, ...StatesModulePipeline<TModule, TSchema>]
  >
}

type QueryReadOf<TSchema extends QueryStateSchema, TDescriptors extends readonly unknown[]>
  = TDescriptors extends readonly [] ? QueryReadMap<TSchema> : /* the base read after the ordered presence effects */

TApi is the API the applied modules contributed and TDescriptors the pipeline descriptors they installed. QueryReadOf applies the resolved-projection presence effects in execution order: an optional effect weakens a read, a required effect strengthens it, and the last effect wins. Earlier aliases keep their earlier types.

The module markers and supporting single-schema types are internal declarations. See Module types for the full composition contract.

Related guide

Query state.