Active params

Derives which params are explicitly present and different from their composed defaults. Use it for active-filter badges, summaries, and per-param indicators without duplicating the comparison policy in application code.

Usage

withActiveParams composes on a group with useQueryStates or on a single param with useQueryState. The group receives aggregate views; the single param receives one computed activity flag.

On a group

import { codecs, useQueryStates } from '@vuqs/core'
import { withActiveParams } from '@vuqs/core/modules'

const query = useQueryStates({
  q: codecs.string,
  status: codecs.literal(['open', 'closed'] as const).withDefault('open'),
  page: codecs.integer.withDefault(1),
}).use(withActiveParams({ exclude: ['page'] }))

query.activeKeys.value // readonly ('q' | 'status' | 'page')[]
query.activeCount.value
query.hasActive.value
query.isActive('status')

exclude removes a param from every grouped view. Its keys are checked against the surrounding schema.

On a single param

import { codecs, useQueryState } from '@vuqs/core'
import { withActiveParams } from '@vuqs/core/modules'

const status = useQueryState(
  'status',
  codecs.literal(['open', 'closed'] as const).withDefault('open'),
).use(withActiveParams())

status.isActive.value

The single-param form takes no options.

See the withActiveParams reference for call forms, options, return values, and types.

Signals

• Emits: none.
• Reacts to: none.

The module derives from shared reactive reads instead. See Composing built-in modules for the built-in interactions that affect those reads.

How it works

Activity rules

A param is active when all these conditions hold:

1. It exists in the explicit state after the read pipeline.
2. It is not excluded.
3. It has no composed default, or its explicit value differs from that default according to the param's equality function.

The explicit value and the composed default are compared as projected by the read pipeline, without filling omitted children. Composed defaults include static defaults and installed default sources, and they stay inspectable while a presence gate keeps the param absent from values. Custom equality from withEquality is respected. Changes to the explicit state, defaults, or read pipeline update the result reactively. Optimistic writes update it before the adapter commits the URL.

Presence is not activity

An explicit value can equal its default. That param is present in the URL, but it is not active.

State	Present	Active
Param absent	no	no
Explicit value with no default	yes	yes
Explicit value different from the default	yes	yes
Explicit value equal to the default	yes	no

A partial object is compared as it is. With structural equality and the default { a: 0, b: 100 }, an explicit { b: 100 } resolves to the default but differs from it, so it is active. The complete { a: 0, b: 100 } is inactive. Keeping a default in the URL with keepOnDefault() does not make it active, and inactivity does not allow the URL representation to be omitted when that would change what the param reads.

Use core.state.explicitValues when authoring a module that needs explicit values regardless of activity. These reads include optimistic writes and the read pipeline.

Example

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,
}))

Debugging

withActiveParams is a read-only projection and emits no module-specific debug events. Use vuqs debug logging to inspect the transactions, pipeline registrations, and default-source changes that feed its computed state.

Nuxt

Under @vuqs/nuxt, withActiveParams is auto-imported with the other modules.