Skip to Content
BBRICKSv0.7.4
DataOverview

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.

HookUse it for
useHashState and useQueryStateAn object of filters in the hash or the query, under a namespace
useUrlParamsThe same, with the place chosen at run time
useUrlSortSort key and direction, restricted to the keys you allow
useListStateA 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, on popstate and on hashchange.
  • Without a window every 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): string

Prop

Type

Source: src/data/urlState.ts (line 31)

readHashParams

function

The params after ? in the hash.

function readHashParams(): URLSearchParams

Source: src/data/urlState.ts (line 34)

readQueryParams

function

The page's search params.

function readQueryParams(): URLSearchParams

Source: 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): URLSearchParams

Prop

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): S

Prop

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): boolean

Prop

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): boolean

Prop

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): boolean

Prop

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): () => void

Prop

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.

On this page