API Reference

`createQsUtils(options?)`

Factory function that creates a reactive query string utility.

import { createQsUtils } from "@vp-tw/nanostores-qs";

const qsUtils = createQsUtils(options?);

Options

Option	Type	Description
`qs`	`{ parse, stringify }`	Custom query string library (default: `URLSearchParams`)
`isEqual`	`(a, b) => boolean`	Custom equality check (default: `es-toolkit` isEqual)

Returned properties

Property	Type	Description
`$search`	`ReadableAtom<string>`	Current `window.location.search` string
`$urlSearchParams`	`ReadableAtom<URLSearchParams>`	Parsed `URLSearchParams` from `$search`
`$qs`	`ReadableAtom<Record<string, unknown>>`	Parsed query object
`createSearchParamStore`	`(name, config?) => Store`	Create a single-parameter store
`createSearchParamsStore`	`(configs) => Store`	Create a multi-parameter store
`destroy`	`() => void`	Remove event listeners and unpatch history

`createSearchParamStore(name, preset?)`

Create a reactive store for a single URL query parameter.

import * as presets from "@vp-tw/nanostores-qs/presets";

const store = qsUtils.createSearchParamStore("page", presets.integer({ default: 1, min: 0 }));

Parameters

Parameter	Type	Description
`name`	`string`	Query parameter name
`config`	`Config`	Preset config or plain config object

Returned store

Property / Method	Type	Description
`$value`	`ReadableAtom<T>`	Current decoded value
`$resolved`	`ReadableAtom<R>`	Resolved value (same as `$value` if no `resolve` set)
`update(value, options?)`	`void`	Update URL with new value
`update.dry(value)`	`string`	Compute next search string without side effects

`createSearchParamsStore(configs)`

Create a reactive store for multiple URL query parameters.

const store = qsUtils.createSearchParamsStore({
  page: presets.integer({ default: 1, min: 0 }),
  sort: presets.enum(["newest", "oldest"]),
});

Parameters

An object mapping parameter names to preset configs.

Returned store

Property / Method	Type	Description
`$values`	`ReadableAtom<Record<string, T>>`	All current decoded values
`$resolved`	`ReadableAtom<Record<string, R>>`	Resolved values (same as `$values` if no `resolve` set)
`update(key, value, options?)`	`void`	Update a single parameter
`update.dry(key, value)`	`string`	Dry-run for single parameter
`updateAll(values, options?)`	`void`	Update all parameters atomically
`updateAll.dry(values)`	`string`	Dry-run for all parameters

Update options

All update and updateAll calls accept an options object:

Option	Type	Default	Description
`replace`	`boolean`	`false`	Use `replaceState` instead of `pushState`
`keepHash`	`boolean`	`false`	Preserve current URL hash
`state`	`unknown`	—	Custom state for History API
`force`	`boolean`	`false`	Bypass equality check

Routing notes

When window is unavailable (SSR), the internal search defaults to an empty string; listeners are not attached.
The utility listens to popstate and patches pushState/replaceState to stay reactive.