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.