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.
| Key | English | Arabic |
|---|---|---|
search | Search | دوّر |
sortBy | Sort by | رتّب حسب |
flipTitle | Flip order (high ↔ low) | اعكس الترتيب (الأعلى ↔ الأقل) |
flip | Flip sort order, now low to high | اعكس الترتيب، دلوقتي من الأقل للأعلى |
reset | Reset filters | امسح الفلاتر |
moreFilters | Filters | الفلاتر |
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
- Row (
div.kit-toolbar.kit-lt): wraps, 10px gap. - Search (
input.kit-lt-q,type="search"): 260px (--lt-search-w) or growing to 420px; labelled "Search" unlesslabel. - Status chips:
FilterChips(dashed.chipfradiogroup). - Selects (
select.kit-lt-sel): the first option ("All tiers") is the visible label;labelis read by AT. - Date (
input.kit-lt-date) and filters (any node, e.g. a Segmented range). - Sort by (
.kit-sortby): label + select + ⇅ flip button (.kit-dirb). - End group (
.kit-toolbar-end): "Reset filters" (only whilereset.active) thenactions. - Extra (
.kit-lt-extra): one more control, inline or on its own row. - Folded filters: a "Filters · n" button and its panel below the row.
Variants
| Prop | Value | Look | When |
|---|---|---|---|
search.width | 'fixed' (default) | 260px box | v3 screenshots |
search.width | 'grow' | Grows to 420px | 0.2 look, search-only bars |
extraPlacement | 'inline' (default) | After actions, wraps only when full | — |
extraPlacement | 'newRow' | Own row at the start, 10px below | PR Portal › Brands (My brands / All brands) |
collapseFiltersBelow | px | Below it: selects/date/filters behind "Filters · n" | Find creators, My creators (600) |
| sort option | [value, label, dir] | Picking it also sets its starting direction | Name A–Z asc, Sales desc |
States
| State | Trigger | Look |
|---|---|---|
| Typing | keystrokes | Field updates now; search.onChange fires after delay (300ms) |
| Filters active | reset.active | "Reset filters" button appears |
| Reset | click Reset | reset.onReset(); pending search dropped |
| Folded | viewport < collapseFiltersBelow | "Filters" or "Filters · 2" (count of selects off their first option + date) with aria-expanded |
| Unknown sort value | sort.value not in options | Shows the first option |
| No sort options | options=[] | 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
- Brand › Creators (search, chips, Tier / Followers / Platform / Group selects, sort, Export CSV), Brand › Find creators (search, 4 selects, sort, folded under 600px), Brand › Coupons, Brand › Payments › Commissions, Brand › Activity log (date filter).
- PR Portal › Creators, Brands (
extraPlacement="newRow"), Gift stock, Affiliate programs › Campaigns. - Screens: Creators, Find creators, Coupons, Payments › Wallet, PR · Creators, PR · Brands, PR · Gift stock, PR · Affiliate programs.
Guidelines
Do
- Make the first option of each select "All …" (it is the visible label).
- Wire
resetso 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
listToolbartable.
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" / "دوّر", orsearch.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'slabel(aria-label), since their first option is the visible label. - Chips: a
FilterChipsradiogroup with one Tab stop and arrow keys. Pass achips.valuethat 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.
Related
DataTable: the list it controls.FilterChips,Segmented,SelectBox: its parts.Toolbar+SortSelect: the older pair it replaces.
See also: Icon · Button · BulkBar · CopyLink · CreatorCell
Source
src/kit/patterns/ListToolbar.tsx (line 145) on GitHub.