URL state
Keep filters, sort and page in the URL: the hooks and the helpers under them.
A list's state belongs in the URL, so a reload, Back and a shared link land on the same view. The library keeps it in the hash query (#coupons?codes.q=kari&codes.status=paused: the part before ? is your view and is kept) or in the page's search query (?q=kari). One small core does both, and every hook that uses it hears every other hook's writes.
| Hook | Use it for |
|---|---|
| useHashState and useQueryState | An object of filters in the hash or the query, under a namespace |
| useUrlParams | The same, with the place chosen at run time |
| useUrlSort | Sort key and direction, restricted to the keys you allow |
| useListState | A whole list: query, rows, loading and errors, all in one |
How writes behave
- A value equal to its default is not written, so the URL stays clean.
- Params the hook does not own are kept.
- One call is one history write. By default it replaces the current entry, so typing never floods history; pass
{ history: 'push' }for a change that Back should undo (opening a drawer, say). - Writes announce themselves with
URL_STATE_EVENT('bc:url'); hooks re-read on it, onpopstateand onhashchange. - Without a
windowevery function reads empty and writes nothing, so the hooks can render on the server.
Filters in the hash
useHashState(namespace, defaults) keeps an object in the URL hash query (#view?codes.q=kari); a value equal to its default leaves the URL; Back and Forward re-read it. The setter writes one history entry for the whole patch, and the third item resets.
Code
import { Button, FilterChips, useHashState } from '@ergasti/bricks';
function Filters() {
const [filters, setFilters, reset] = useHashState('docs-codes', { q: '', status: 'all' });
return (
<div style={{ display: 'grid', gap: 10 }}>
<input aria-label="Search codes" placeholder="Search codes" value={filters.q} onChange={(e) => setFilters({ q: e.target.value })} />
<FilterChips label="Status" value={filters.status} onChange={(status) => setFilters({ status })} options={[{ value: 'all', label: 'All' }, { value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }]} />
<div><Button size="sm" onClick={reset}>Reset</Button> <small>{JSON.stringify(filters)}</small></div>
</div>
);
}The functions under the hooks
URL_STATE_EVENT
constant
The event a URL-state write dispatches (the same name the console's urlState.ts and useListState use).
const URL_STATE_EVENT: "bc:url"Source: src/data/urlState.ts (line 10)
paramName
function
A param's name: bare for namespace '', else namespace.field (two lists on one screen keep separate state).
function paramName(namespace: string, field: string): stringProp
Type
Source: src/data/urlState.ts (line 31)
readHashParams
function
The params after ? in the hash.
function readHashParams(): URLSearchParamsSource: src/data/urlState.ts (line 34)
readQueryParams
function
The page's search params.
function readQueryParams(): URLSearchParamsSource: src/data/urlState.ts (line 42)
readParams
function
Reads the URL params from the hash query ('hash') or the page's search query ('query'). Empty without a window, so it is safe on the server.
function readParams(location: UrlLocation): URLSearchParamsProp
Type
Source: src/data/urlState.ts (line 46)
readNamespaced
function
defaults with whatever the URL says for each field under namespace. Fields not in defaults are ignored.
function readNamespaced<S>(location: UrlLocation, namespace: string, defaults: S): SProp
Type
Source: src/data/urlState.ts (line 98)
writeHashParams
function
Set (or with null / undefined / '' drop) params in the hash query in ONE history write; params not in the patch are kept. Returns whether the URL changed (no change → no write, no event). An empty hash never becomes #.
function writeHashParams(patch: UrlPatch, options?: WriteOptions): booleanProp
Type
Source: src/data/urlState.ts (line 69)
writeQueryParams
function
Set (or drop) params in the page's search query in one history write; the hash is kept.
function writeQueryParams(patch: UrlPatch, options?: WriteOptions): booleanProp
Type
Source: src/data/urlState.ts (line 79)
writeParams
function
Writes URL params into the hash query or the search query in one history write ('replace' by default, 'push' on request). A value of null, undefined or '' removes the param. Returns false when nothing changed, and announces a change with URL_STATE_EVENT so the URL hooks re-read.
function writeParams(location: UrlLocation, patch: UrlPatch, options?: WriteOptions | undefined): booleanProp
Type
Source: src/data/urlState.ts (line 86)
toNamespacedPatch
function
A patch of fields → URL params under namespace; a value equal to its default leaves the URL, and '' against a non-empty default is written as an explicit empty param (EMPTY_PARAM), so it reads back as ''.
function toNamespacedPatch<S>(namespace: string, patch: Partial<S>, defaults: S): Record<string, string | typeof EMPTY_PARAM | null>Prop
Type
Source: src/data/urlState.ts (line 111)
subscribeUrl
function
Call listener on Back / Forward, a hash link, or any URL-state write. Returns the unsubscribe.
function subscribeUrl(listener: () => void): () => voidProp
Type
Source: src/data/urlState.ts (line 90)
LIST_STATE_EVENT
constant
deprecated
Deprecated
Since 0.2.0: use URL_STATE_EVENT (the same value). Removed in 1.0.
The event other URL-state code listens to: an alias of data/urlState's URL_STATE_EVENT (bc:url).
const LIST_STATE_EVENT: "bc:url"Source: src/hooks/useListState.ts (line 57)
LIST_STATE_EVENT is deprecated since 0.2.0: it is the same value as URL_STATE_EVENT, kept from the earlier list hook, and is removed in 1.0. Listen for URL_STATE_EVENT in new code; useListState's writes and the URL hooks' writes wake each other either way.