ListState
Loading, failed (with a retry) or empty: the three things a list says instead of rows.
import { ListState } from '@ergasti/bricks';Examples
One list state at a time
loading and error win over empty; the error has a Retry button. It renders nothing when none applies.
Code
import { ListState } from '@ergasti/bricks';
function States() {
return (
<div style={{ display: 'grid', gap: 12 }}>
<ListState loading error={null} empty={false} emptyText="Nothing matches" onRetry={() => {}} />
<ListState loading={false} error="We could not load the list." empty={false} emptyText="Nothing matches" onRetry={() => {}} />
<ListState loading={false} error={null} empty emptyText="Nothing matches" onRetry={() => {}} />
</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 listState, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
retry | Try again | جرّب تاني |
loading | Loading… | جارٍ التحميل… |
Design guidance
How the BRICKS design system uses ListState. Written in docs/content/components/ListState.md; the props above are read from the code, which wins where the two disagree.
The line a list shows instead of rows: "Loading…", an error with "Try again", or your empty text; use it under 0.1.x lists that manage their own fetching.
ListState returns at most one paragraph, chosen in order: an error (with a retry button) wins, then loading (only while the list is empty, so a refresh does not hide rows), then empty. With rows to show it renders nothing. RowList uses it internally.
Anatomy
- Paragraph (
p.console-list-state): 13px muted text, line-height 1.6. - Retry button (error only): 44px tall outlined button "Try again".
Variants
None; the state is the variant.
States
| State | Trigger | Look | AT |
|---|---|---|---|
| Error | error string | Red text + "Try again" / "جرّب تاني" | role="alert" |
| Loading | loading && empty | "Loading…" / "جارٍ التحميل…" | aria-live="polite" |
| Empty | empty | emptyText | plain |
| Rows | none of the above | Nothing | — |
Usage
function Coupons({ query }: { query: string }) {
const coupons = useResource<Array<{ id: number; code: string }>>('/coupons', { params: { q: query } });
const empty = !coupons.data || coupons.data.length === 0;
return (
<>
<ListState loading={coupons.status === 'loading'} error={coupons.error?.message ?? null} empty={empty}
emptyText="No coupons match these filters." onRetry={coupons.reload} />
{!empty && <ul>{coupons.data.map((c) => <li key={c.id}><CouponChip code={c.code} /></li>)}</ul>}
</>
);
}Where it appears
- 0.1.x console lists and
RowList. v3DataTablehas its ownloading/error/emptyprops. - Kit gallery.
Guidelines
Do
- Write
emptyTextfor the filters in use ("No coupons match these filters."). - Pass a human error message, not a status code.
Don't
- Don't use it beside a
DataTable; use the table's own states.
RTL and Arabic
- Text follows the page; Arabic copy for "Try again" and "Loading…".
Tokens
None (fixed console colours #667085, #B42318, #D9DFEA).
Accessibility
- Error: a
role="alert"paragraph, announced when it appears, with a native "Try again" button (44px tall, a 2px ink focus outline from the console list styles). - Loading: "Loading…" in an
aria-live="polite"paragraph. It mounts with its text, so some screen readers do not announce it; keeparia-busyon the list container if the wait matters. - Empty: plain text, not announced on its own; it is read when reached.
Found in the source
- Roles in the markup:
alert. - ARIA attributes set:
aria-label,aria-live,aria-hidden,aria-current.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
DataTableloading/error/empty.AsyncBlock: loading/error/empty for any block.EmptyView: a full empty screen.
See also: BulkBar · CopyLink · CreatorCell
Source
src/kit/ListControls.tsx (line 141) on GitHub.