Skip to Content
BBRICKSv0.7.4
DataHooks

useListState

One list's state and data (replaces the console's usePagedList + usePaged and urlState + useHashState): q, chip, selects, sort, dir and page live in the hash under namespace, so reload, Back and a shared link land on the same list. Any filter or sort change goes back to page 1; each change aborts the previous request. If the last page empties (a row was removed), it steps back to the new last page.

import { useListState } from '@ergasti/bricks';

Examples

One list's state

Search, chip, selects, sort and page live in the URL hash under namespace (here inHash: false keeps this docs page's URL clean); any filter or sort change goes back to page 1, each change aborts the previous request, and an emptied last page steps back.

Code
import { Button, DataTable, ListToolbar, Pager, useListState, type DataColumn, type ListPage, type ListQuery } from '@ergasti/bricks';
import { creators, type Creator } from './sample-data';

const serve = async (q: ListQuery): Promise<ListPage<Creator>> => {
  await new Promise((resolve) => window.setTimeout(resolve, 300));
  const rows = creators.filter((c) => (!q.q || c.name.toLowerCase().includes(q.q.toLowerCase())) && (!q.chip || q.chip === 'all' || c.status.toLowerCase() === q.chip));
  const sorted = [...rows].sort((a, b) => {
    const [x, y] = q.sort === 'name' ? [a.name, b.name] : [a.sales, b.sales];
    return (x > y ? 1 : x < y ? -1 : 0) * (q.dir === 'asc' ? 1 : -1);
  });
  return { rows: sorted.slice((q.page - 1) * 5, q.page * 5), total: rows.length, lastPage: Math.max(1, Math.ceil(rows.length / 5)) };
};

const columns: DataColumn<Creator>[] = [
  { key: 'name', label: 'Creator', sortKey: 'name', sortFirst: 'asc', render: (c) => c.name },
  { key: 'status', label: 'Status', render: (c) => c.status },
  { key: 'sales', label: 'Sales', sortKey: 'sales', align: 'end', render: (c) => c.sales.toLocaleString('en-US') },
];

function Creators() {
  const list = useListState<Creator>({ namespace: 'docs', inHash: false, defaults: { chip: 'all', sort: 'sales', dir: 'desc' }, fetcher: serve });
  return (
    <div>
      <ListToolbar
        search={{ value: list.query.q, onChange: (q) => list.set({ q }), placeholder: 'Search creators' }}
        chips={{ label: 'Status', value: list.query.chip, onChange: (chip) => list.set({ chip }), options: [{ value: 'all', label: 'All' }, { value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }] }}
        reset={{ active: list.query.q !== '' || list.query.chip !== 'all', onReset: list.reset }}
        actions={<Button size="sm" onClick={list.retry}>Reload</Button>}
      />
      <DataTable
        label="Creators" columns={columns} rows={list.rows} rowKey={(c) => c.id} loading={list.loading} onClearFilters={list.reset}
        sort={{ key: list.query.sort, dir: list.query.dir }} onSort={(s) => list.set({ sort: s.key, dir: s.dir })}
        footer={<Pager page={list.page} lastPage={list.lastPage} total={list.total} perPage={5} loading={list.loading} label="Creators" onPage={(page) => list.set({ page })} />}
      />
    </div>
  );
}

Signature

function useListState<T>(options: ListStateOptions<T>): ListState<T>

Parameters

options: ListStateOptions<T> (required)

Prop

Type

Returns

ListState<T>

ListToolbar · Button · DataTable · Pager · useAction · useDataLanguage · useDebouncedCallback · useDrawerResource

Source

src/hooks/useListState.ts (line 101) on GitHub.

On this page