Skip to Content
BBRICKSv0.7.4
KitLists and tables

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.

listState
KeyEnglishArabic
retryTry againجرّب تاني
loadingLoading…جارٍ التحميل…

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

  1. Paragraph (p.console-list-state): 13px muted text, line-height 1.6.
  2. Retry button (error only): 44px tall outlined button "Try again".

Variants

None; the state is the variant.

States

StateTriggerLookAT
Errorerror stringRed text + "Try again" / "جرّب تاني"role="alert"
Loadingloading && empty"Loading…" / "جارٍ التحميل…"aria-live="polite"
EmptyemptyemptyTextplain
Rowsnone of the aboveNothing—

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. v3 DataTable has its own loading / error / empty props.
  • Kit gallery.

Guidelines

Do

  • Write emptyText for 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; keep aria-busy on 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.

See also: BulkBar · CopyLink · CreatorCell

Source

src/kit/ListControls.tsx (line 141) on GitHub.

On this page