Skip to Content
BBRICKSv0.7.4
KitLists and tables

ListToolbar

The v3 list toolbar (the mock's tbl() tools), the standard toolbar of every list: search, status chips, filter selects, any other filter, "Sort by" with the ⇅ flip button, then "Reset filters" and an Export CSV slot pushed to the end, and an extra control after them (or on a row of its own, extraPlacement="newRow"). Every part is optional. Controlled: the screen (useListState) holds the values; any filter change there resets the page to 1. It replaces Toolbar + SortSelect.

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

Examples

The list toolbar

Search (it waits for a pause in typing), status chips, selects, your own filters, sort with a flip button, a reset that appears while a filter is set, and actions. Everything is controlled.

Code
import { useState } from 'react';
import { Button, ListToolbar, Segmented } from '@ergasti/bricks';

function Full() {
  const [q, setQ] = useState('');
  const [chip, setChip] = useState('all');
  const [tier, setTier] = useState('');
  const [range, setRange] = useState('all');
  const [sort, setSort] = useState('sales');
  const [dir, setDir] = useState<'asc' | 'desc'>('desc');
  return (
    <ListToolbar
      search={{ value: q, onChange: setQ, placeholder: 'Search name, @handle or coupon' }}
      chips={{ label: 'Status', value: chip, onChange: setChip, options: [{ value: 'all', label: 'All' }, { value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }, { value: 'removed', label: 'Removed' }] }}
      selects={[{ id: 'docs-tier', label: 'Tier', value: tier, onChange: setTier, options: [['', 'All tiers'], ['rising', 'Rising'], ['elite', 'Elite']] }]}
      filters={<Segmented label="Joined" value={range} onChange={setRange} options={[['all', 'Any time'], ['30', '30 days'], ['90', '90 days']]} />}
      sort={{ value: sort, dir, onChange: (key, next) => { setSort(key); if (next) setDir(next); }, onFlip: () => setDir(dir === 'asc' ? 'desc' : 'asc'), options: [['sales', 'Sales', 'desc'], ['orders', 'Orders', 'desc'], ['name', 'Name (A–Z)', 'asc']] }}
      reset={{ active: q !== '' || chip !== 'all' || tier !== '' || range !== 'all', onReset: () => { setQ(''); setChip('all'); setTier(''); setRange('all'); } }}
      actions={<Button size="sm">Export CSV</Button>}
    />
  );
}

Wide search and folded filters

search.width="grow" is the 420px search box (default 'fixed': the theme hook --lt-search-w, 260px, or 248px under the pr theme). collapseFiltersBelow={600} folds the selects and filters behind a "Filters · n" button under 600px of viewport width, so a phone reaches the list sooner; resize the window to try it.

Code
import { useState } from 'react';
import { ListToolbar } from '@ergasti/bricks';

function GrowAndCollapse() {
  const [q, setQ] = useState('');
  const [tier, setTier] = useState('');
  const [status, setStatus] = useState('');
  return (
    <ListToolbar
      search={{ value: q, onChange: setQ, placeholder: 'Search name, @handle or coupon', width: 'grow' }}
      selects={[
        { id: 'docs-tier-2', label: 'Tier', value: tier, onChange: setTier, options: [['', 'All tiers'], ['rising', 'Rising'], ['elite', 'Elite']] },
        { id: 'docs-status-2', label: 'Status', value: status, onChange: setStatus, options: [['', 'Any status'], ['active', 'Active'], ['paused', 'Paused']] },
      ]}
      collapseFiltersBelow={600}
    />
  );
}

A control after the actions

extra adds one more control (a My brands / All brands switch) after Export CSV, inside the toolbar: when the row is full it wraps 10px under it; with no actions it sits at the end of the row.

Code
import { useState } from 'react';
import { Button, ListToolbar, Segmented } from '@ergasti/bricks';

function Extra() {
  const [q, setQ] = useState('');
  const [scope, setScope] = useState<'my' | 'all'>('my');
  const [status, setStatus] = useState('');
  return (
    <ListToolbar
      search={{ value: q, onChange: setQ, placeholder: 'Search brands' }}
      selects={[{ id: 'docs-status-3', label: 'Status', value: status, onChange: setStatus, options: [['', 'All statuses'], ['active', 'Active'], ['paused', 'Paused']] }]}
      actions={<Button size="sm">Export CSV</Button>}
      extra={<Segmented size="sm" label="Brands shown" value={scope} onChange={setScope} options={[['my', 'My brands'], ['all', 'All brands']]} />}
    />
  );
}

Extra on its own row

extraPlacement="newRow" always starts a second row with extra, at the start side 10px under the controls (the PR Brands page's My brands / All brands switch); the default 'inline' keeps it after the actions.

Code
import { useState } from 'react';
import { Button, ListToolbar, Segmented } from '@ergasti/bricks';

function ExtraOnNewRow() {
  const [q, setQ] = useState('');
  const [scope, setScope] = useState<'my' | 'all'>('my');
  return (
    <ListToolbar
      search={{ value: q, onChange: setQ, placeholder: 'Search brands or PR owner' }}
      actions={<Button size="sm">Export CSV</Button>}
      extraPlacement="newRow"
      extra={<Segmented size="sm" label="Brands shown" value={scope} onChange={setScope} options={[['my', 'My brands'], ['all', 'All brands']]} />}
    />
  );
}

A day filter

date adds a labelled date input after the selects (the Activity log's day, 160 × 42); it counts in the folded "Filters · n", and Reset filters is where you clear it.

Code
import { useState } from 'react';
import { Button, ListToolbar } from '@ergasti/bricks';

function WithDate() {
  const [chip, setChip] = useState('all');
  const [day, setDay] = useState('');
  return (
    <ListToolbar
      chips={{ label: 'Category', value: chip, onChange: setChip, options: [{ value: 'all', label: 'All' }, { value: 'creators', label: 'Creators' }, { value: 'payments', label: 'Payments' }] }}
      date={{ label: 'Day', value: day, onChange: setDay }}
      reset={{ active: chip !== 'all' || day !== '', onReset: () => { setChip('all'); setDay(''); } }}
      actions={<Button size="sm">Export CSV</Button>}
    />
  );
}

The fixed search width

A 'fixed' search box reads the theme hook --lt-search-w (default 260px, the brand mock; the pr theme sets the PR mock's 248px). Set it on a wrapper or in your theme to match another layout; use search.width="grow" instead when the box should take the free space.

Code
import { useState, type CSSProperties } from 'react';
import { Button, ListToolbar } from '@ergasti/bricks';

function SearchWidth() {
  const [q, setQ] = useState('');
  return (
    <div style={{ '--lt-search-w': '200px' } as CSSProperties}>
      <ListToolbar search={{ value: q, onChange: setQ, placeholder: 'Search brands' }} actions={<Button size="sm">Export CSV</Button>} />
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key listToolbar, or with the component's own prop where it has one. A {name} is a value the component fills in.

listToolbar
KeyEnglishArabic
searchSearchدوّر
sortBySort byرتّب حسب
flipTitleFlip order (high ↔ low)اعكس الترتيب (الأعلى ↔ الأقل)
flipFlip sort order, now low to highاعكس الترتيب، دلوقتي من الأقل للأعلى
resetReset filtersامسح الفلاتر
moreFiltersFiltersالفلاتر

Design guidance

How the BRICKS design system uses ListToolbar. Written in docs/content/components/ListToolbar.md; the props above are read from the code, which wins where the two disagree.

The standard toolbar above every v3 list: search, status chips, filter selects, a date or custom filter, "Sort by" with a flip button, "Reset filters" and an actions slot; use it on top of a DataTable.

ListToolbar is the mock's tbl() tools row. Every part is optional and controlled: the screen (usually useListState) holds the values, and any filter change there resets the page to 1. The search box types at once and reports after a 300ms pause; Reset clears a pending keystroke too. On phones, collapseFiltersBelow folds the selects and filters behind one "Filters · n" button so the list is reached sooner. It replaces Toolbar + SortSelect.

Anatomy

  1. Row (div.kit-toolbar.kit-lt): wraps, 10px gap.
  2. Search (input.kit-lt-q, type="search"): 260px (--lt-search-w) or growing to 420px; labelled "Search" unless label.
  3. Status chips: FilterChips (dashed .chipf radiogroup).
  4. Selects (select.kit-lt-sel): the first option ("All tiers") is the visible label; label is read by AT.
  5. Date (input.kit-lt-date) and filters (any node, e.g. a Segmented range).
  6. Sort by (.kit-sortby): label + select + ⇅ flip button (.kit-dirb).
  7. End group (.kit-toolbar-end): "Reset filters" (only while reset.active) then actions.
  8. Extra (.kit-lt-extra): one more control, inline or on its own row.
  9. Folded filters: a "Filters · n" button and its panel below the row.

Variants

PropValueLookWhen
search.width'fixed' (default)260px boxv3 screenshots
search.width'grow'Grows to 420px0.2 look, search-only bars
extraPlacement'inline' (default)After actions, wraps only when full—
extraPlacement'newRow'Own row at the start, 10px belowPR Portal › Brands (My brands / All brands)
collapseFiltersBelowpxBelow it: selects/date/filters behind "Filters · n"Find creators, My creators (600)
sort option[value, label, dir]Picking it also sets its starting directionName A–Z asc, Sales desc

States

StateTriggerLook
TypingkeystrokesField updates now; search.onChange fires after delay (300ms)
Filters activereset.active"Reset filters" button appears
Resetclick Resetreset.onReset(); pending search dropped
Foldedviewport < collapseFiltersBelow"Filters" or "Filters · 2" (count of selects off their first option + date) with aria-expanded
Unknown sort valuesort.value not in optionsShows the first option
No sort optionsoptions=[]No Sort by

Usage

Brand › Creators › My creators:

<Card>
  <ListToolbar<Chip, SortKey>
    search={{ value: q, onChange: setQ, placeholder: 'Search name, @handle or coupon' }}
    chips={{ label: 'Status', value: chip, onChange: setChip, options: [
      { value: 'all', label: 'All' }, { value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }, { value: 'removed', label: 'Removed' }] }}
    selects={[{ id: 'cr-tier', label: 'Tier', value: tier, onChange: setTier,
      options: [['', 'All tiers'], ['rising', 'Rising'], ['established', 'Established'], ['elite', 'Elite']] }]}
    sort={{ value: sort, dir, options: [['name', 'Name (A–Z)', 'asc'], ['score', 'Score', 'desc'], ['sales', 'Sales', 'desc'], ['joined', 'Newest', 'desc']],
      onChange: (s, d) => { setSort(s); if (d) setDir(d); }, onFlip: () => setDir(dir === 'asc' ? 'desc' : 'asc') }}
    reset={{ active: q !== '' || chip !== 'all' || tier !== '', onReset: resetAll }}
    actions={<Button size="sm">Export CSV</Button>}
    collapseFiltersBelow={600} />
  <DataTable label="My creators" columns={columns} rows={rows} rowKey={(c) => c.id} sort={{ key: sort, dir }}
    onSort={(s) => { setSort(s.key as SortKey); setDir(s.dir); }} footer={<Pager page={1} lastPage={31} total={304} perPage={10} loading={false} label="My creators" onPage={setPage} />} />
</Card>

With useListState:

<ListToolbar search={{ value: list.query.q, onChange: (q) => list.set({ q }) }}
  chips={{ label: 'Status', value: list.query.chip, onChange: (chip) => list.set({ chip }), options: statusOptions }}
  reset={{ active: list.query.q !== '' || list.query.chip !== 'all', onReset: list.reset }} />

PR Portal › Brands, scope on its own row:

<ListToolbar search={{ value: q, onChange: setQ, placeholder: 'Search brands or PR owner' }}
  extraPlacement="newRow"
  extra={<Segmented size="sm" label="Brands to show" value={scope} onChange={setScope} options={[['mine', 'My brands'], ['all', 'All brands']]} />} />

Where it appears

Guidelines

Do

  • Make the first option of each select "All …" (it is the visible label).
  • Wire reset so users can get back to the default list in one click.
  • Put Export CSV in actions.
  • Keep the search placeholder to about 26 characters: the fixed 260px box cuts longer text ("Search name, @handle or coupon" is clipped to "…coupo" on My creators). Shorten it ("Search name or coupon") or use width: 'grow'.
  • Use collapseFiltersBelow={600} when there are three or more selects.

Don't

  • Don't put a second search on the page.
  • Don't use it without a list under it.

RTL and Arabic

  • The row flows right to left; the end group goes to the left. Search is dir="auto".
  • Arabic copy: "رتّب حسب", "دوّر", reset and filters labels from the listToolbar table.

Tokens

--lt-search-w, --line, --card, --ink, --ink-2, --ink-3, --rasp, --focus-ring, --focus-ring-field, --kit-chevron, --min-touch-target.

Accessibility

  • Search: an aria-label ("Search" / "دوّر", or search.label); the placeholder is not its name. Results are not announced by the toolbar: the Pager's polite summary below the list says the new count.
  • Selects: native <select>s named by each select's label (aria-label), since their first option is the visible label.
  • Chips: a FilterChips radiogroup with one Tab stop and arrow keys. Pass a chips.value that is one of the options: with a value that matches none, no chip shows as selected (the first chip is then the tab stop).
  • Sort: a labelled <select> ("Sort by") and the flip button named "Flip sort order, now high to low", with the title "Flip order (high ↔ low)".
  • Folded filters: the "Filters · n" button has aria-expanded / aria-controls.
  • "Reset filters" is a real button with its icon hidden; it appears only while a filter is set.

Found in the source

  • ARIA attributes set: aria-label, aria-expanded, aria-controls, aria-hidden.
  • Its tests cover: “search tells the list once typing pauses (300 ms), not per key; an outside reset refills the box”; “keyboard: arrows move the chips, the selects change, the flip button works with Enter”; “Arabic + RTL: Arabic labels; ArrowLeft moves forward through the chips in RTL”; “an unknown sort value shows the first option (as SortSelect did); no options, no Sort by; a custom label and a filters slot”; “a keystroke still waiting for the debounce is dropped by Reset filters, never sent after it”; “a labelled date input after the selects, controlled, with min / max; changes call onChange”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Icon · Button · BulkBar · CopyLink · CreatorCell

Source

src/kit/patterns/ListToolbar.tsx (line 145) on GitHub.

On this page