Skip to Content
BBRICKSv0.7.4
KitLists and tables

RowList

The plain row list: the v3 table look (.tbl) with ARIA table roles on a CSS grid. Below 860px each row becomes a two-column card and each cell shows its column label (kit.css). For sortable headers, skeleton rows, the "Clear filters" empty state or a cards mode use DataTable; RowList's own sorting is deprecated.

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

Examples

Plain list

The non-sortable list of rows (RowList's sorting props are deprecated; use DataTable when a header should sort). type sets how a cell is drawn. The status words come from the TRNDR preset, so this example is pinned to it.

Pinned to TRNDR preset
Code
import { PersonCell, PlatformFollowers, RowList, StatusPill, type Column } from '@ergasti/bricks';
import { mock } from './sample-data';

type Request = (typeof mock.REQUESTS)[number];

function Requests() {
  const columns: Column<Request & { i: number }>[] = [
    { id: 'creator', header: 'Creator', type: 'text', width: '1.4fr', cell: (r) => <PersonCell id={r.i} name={r.name} identity={{ handle: null, invitedByYou: false, links: null, avatarUrl: null }} /> },
    { id: 'followers', header: 'Followers by platform', type: 'text', width: '1.6fr', cell: (r) => <PlatformFollowers followers={{ instagram: r.ig, tiktok: r.tt, youtube: r.yt }} /> },
    { id: 'date', header: 'Requested', type: 'text', width: '1fr', cell: (r) => <span className="kit-muted">{r.date}</span> },
    { id: 'status', header: 'Status', type: 'text', width: '.9fr', cell: () => <StatusPill status="with_trndr" /> },
  ];
  return <RowList label="Join requests" columns={columns} rows={mock.REQUESTS.slice(0, 4).map((r, i) => ({ ...r, i }))} rowKey={(r) => r.id} onRowClick={() => {}} />;
}

Empty

Code
import { RowList } from '@ergasti/bricks';

function Empty() {
  return <RowList label="Join requests" columns={[]} rows={[]} rowKey={() => 0} empty={<p className="kit-muted">No join requests yet</p>} />;
}

Loading

loading with no rows yet shows the kit's loading line in place of the table.

Code
import { PersonCell, RowList, type Column } from '@ergasti/bricks';
import { creators } from './sample-data';

type Person = (typeof creators)[number];

const people: Column<Person>[] = [
  { id: 'creator', header: 'Creator', type: 'main', width: '1.6fr', sortKey: 'name', cell: (c) => <PersonCell id={c.id} name={c.name} identity={c.identity} tier={c.tier} photo avatarSrc={c.identity.avatarUrl ?? undefined} sub={c.status} onOpen={() => {}} /> },
  { id: 'orders', header: 'Orders', type: 'num', width: '.8fr', sortKey: 'orders', cell: (c) => c.orders },
  { id: 'sales', header: 'Sales', type: 'num', width: '1fr', sortKey: 'sales', cell: (c) => c.sales.toLocaleString('en') },
];

function Loading() {
  return <RowList label="Creators" columns={people} rows={[]} rowKey={(c) => c.id} loading />;
}

Error with Try again

error takes the reason; onRetry puts a "Try again" button beside it. The error wins over rows.

Code
import { useState } from 'react';
import { PersonCell, RowList, type Column } from '@ergasti/bricks';
import { creators } from './sample-data';

type Person = (typeof creators)[number];

const people: Column<Person>[] = [
  { id: 'creator', header: 'Creator', type: 'main', width: '1.6fr', sortKey: 'name', cell: (c) => <PersonCell id={c.id} name={c.name} identity={c.identity} tier={c.tier} photo avatarSrc={c.identity.avatarUrl ?? undefined} sub={c.status} onOpen={() => {}} /> },
  { id: 'orders', header: 'Orders', type: 'num', width: '.8fr', sortKey: 'orders', cell: (c) => c.orders },
  { id: 'sales', header: 'Sales', type: 'num', width: '1fr', sortKey: 'sales', cell: (c) => c.sales.toLocaleString('en') },
];

function ErrorRetry() {
  const [tries, setTries] = useState(0);
  return <RowList label="Creators" columns={people} rows={[]} rowKey={(c) => c.id} error={`Could not load creators (attempt ${tries + 1}).`} onRetry={() => setTries((n) => n + 1)} />;
}

Empty, plain text

With no empty node, emptyText is the sentence the kit's empty state shows.

Code
import { PersonCell, RowList, type Column } from '@ergasti/bricks';
import { creators } from './sample-data';

type Person = (typeof creators)[number];

const people: Column<Person>[] = [
  { id: 'creator', header: 'Creator', type: 'main', width: '1.6fr', sortKey: 'name', cell: (c) => <PersonCell id={c.id} name={c.name} identity={c.identity} tier={c.tier} photo avatarSrc={c.identity.avatarUrl ?? undefined} sub={c.status} onOpen={() => {}} /> },
  { id: 'orders', header: 'Orders', type: 'num', width: '.8fr', sortKey: 'orders', cell: (c) => c.orders },
  { id: 'sales', header: 'Sales', type: 'num', width: '1fr', sortKey: 'sales', cell: (c) => c.sales.toLocaleString('en') },
];

function EmptyText() {
  return <RowList label="Creators" columns={people} rows={[]} rowKey={(c) => c.id} emptyText="No creators match these filters." />;
}

Selection and dimmed rows

selection adds a checkbox column (with select-all for the page); isDim greys rows such as removed creators.

Code
import { useState } from 'react';
import { PersonCell, RowList, type Column } from '@ergasti/bricks';
import { creators } from './sample-data';

type Person = (typeof creators)[number];

const people: Column<Person>[] = [
  { id: 'creator', header: 'Creator', type: 'main', width: '1.6fr', sortKey: 'name', cell: (c) => <PersonCell id={c.id} name={c.name} identity={c.identity} tier={c.tier} photo avatarSrc={c.identity.avatarUrl ?? undefined} sub={c.status} onOpen={() => {}} /> },
  { id: 'orders', header: 'Orders', type: 'num', width: '.8fr', sortKey: 'orders', cell: (c) => c.orders },
  { id: 'sales', header: 'Sales', type: 'num', width: '1fr', sortKey: 'sales', cell: (c) => c.sales.toLocaleString('en') },
];

function Selection() {
  const [selected, setSelected] = useState<Set<string | number>>(new Set([creators[1].id]));
  return (
    <div style={{ display: 'grid', gap: 10 }}>
      <small className="kit-muted">{selected.size} selected</small>
      <RowList
        label="Creators" columns={people} rows={creators.slice(0, 5)} rowKey={(c) => c.id}
        selection={{ selected, onChange: setSelected, rowLabel: (c) => `Select ${c.name}` }}
        isDim={(c) => c.status === 'Removed'}
      />
    </div>
  );
}

Sortable headers (deprecated)

sort and onSort still work for columns with a sortKey; new code should use DataTable, which also sorts from the URL. The app sorts the rows.

Code
import { useState } from 'react';
import { Button, PersonCell, RowList, type Column, type SortState } from '@ergasti/bricks';
import { creators } from './sample-data';

type Person = (typeof creators)[number];

const people: Column<Person>[] = [
  { id: 'creator', header: 'Creator', type: 'main', width: '1.6fr', sortKey: 'name', cell: (c) => <PersonCell id={c.id} name={c.name} identity={c.identity} tier={c.tier} photo avatarSrc={c.identity.avatarUrl ?? undefined} sub={c.status} onOpen={() => {}} /> },
  { id: 'orders', header: 'Orders', type: 'num', width: '.8fr', sortKey: 'orders', cell: (c) => c.orders },
  { id: 'sales', header: 'Sales', type: 'num', width: '1fr', sortKey: 'sales', cell: (c) => c.sales.toLocaleString('en') },
];

function Sorted() {
  const [sort, setSort] = useState<SortState | null>({ key: 'sales', dir: 'desc' });
  const rows = [...creators.slice(0, 5)].sort((a, b) => {
    if (!sort) return 0;
    const k = sort.key as 'name' | 'orders' | 'sales';
    const d = a[k] < b[k] ? -1 : a[k] > b[k] ? 1 : 0;
    return sort.dir === 'asc' ? d : -d;
  });
  return (
    <div style={{ display: 'grid', gap: 10 }}>
      <RowList label="Creators" columns={people} rows={rows} rowKey={(c) => c.id} sort={sort} onSort={setSort} />
      <div><Button size="sm" onClick={() => setSort(null)}>Clear sort</Button></div>
    </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 rowList, or with the component's own prop where it has one. A {name} is a value the component fills in.

rowList
KeyEnglishArabic
allSelect allاختار الكل
oneSelect {name}اختار {name}

Design guidance

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

The plain 0.1.x row list: the v3 table look built from ARIA table roles on a CSS grid, with typed cells, selection and row opening; prefer DataTable for new lists.

RowList draws a role="table" grid whose tracks come from each column's width, with an uppercase head row, typed cells (main, text, num, chip, code, link, btns) and, under 860px, a two-column card per row with each cell's header as its label. Rows can open on click or Enter (with a chevron track), carry a checkbox column, and be dimmed. Its header sorting is deprecated since 0.2.0: sortable lists, skeleton rows, the "Clear filters" empty state and cards mode belong to DataTable.

Anatomy

  1. Grid (div.kit-tbl, role="table", --cols = tracks).
  2. Head row (.kit-tbl-head, role="row"): columnheaders with the header, a term, or a figure's "?".
  3. Rows (.kit-tbl-row): cells per column type; num is LTR tabular, code is a mono <code>.
  4. Checkbox track (28px, with selection) and chevron track (20px, with onRowClick).
  5. Empty / state (.kit-empty): your empty, or ListState (loading / error / emptyText).

Variants

Column typeCell
'main'The lead cell (spans both card columns on phones)
'text'Plain text
'num'dir="ltr" tabular figure; tone 'good' | 'bad' | 'mut'
'chip'A pill
'code'Mono <code>
'link'A link / CopyLink
'btns'Row action buttons

States

StateTriggerLook
RowsdataGrid
ClickableonRowClickHover --row-hover, chevron, Enter opens
SelectedselectionCheckbox checked, tinted row
DimmedisDim(row)--soft row
Loading (empty)loading and no rows"Loading…"
ErrorerrorError + "Try again" (onRetry)
Emptyno rowsempty or emptyText
Sorted (deprecated)sort + onSort + column sortKeySort button with arrow, aria-sort

Types

Column<R>: id, header (string, also the phone card label), type, cell, width (grid track, default minmax(0, 1fr)), tone, full, figure, term, sortKey (deprecated), sortFirst (deprecated).

Selection<R> (selection): { selected, onChange, rowLabel }.

Usage

<RowList label="Coupons" rowKey={(c) => c.id} rows={coupons} emptyText="No coupons yet." onRowClick={(c) => openCoupon(c.id)}
  columns={[
    { id: 'creator', header: 'Creator', type: 'main', width: 'minmax(0, 2fr)', cell: (c) => <MainCell id={c.creatorId} name={c.creatorName} hint={c.code} /> },
    { id: 'code', header: 'Coupon', type: 'code', cell: (c) => c.code },
    { id: 'uses', header: 'Uses', type: 'num', cell: (c) => c.uses },
    { id: 'sales', header: 'Sales', type: 'num', figure: 'sales', cell: (c) => <Money value={c.sales} /> },
    { id: 'status', header: 'Status', type: 'chip', cell: (c) => <StatusPill status={c.status} /> },
  ]} />

Migrating to DataTable: id → key, header → label, cell → render, type: 'num' → align: 'end', sortKey stays.

Where it appears

  • 0.1.x console lists; not used by the v3 screens (they use DataTable).
  • Kit gallery.

Guidelines

Do

  • Use DataTable for anything new or sortable.

Don't

  • Don't add sorting to RowList; it is deprecated.

RTL and Arabic

  • Grid tracks follow the page direction; num and code cells stay LTR.

Tokens

--tbl-head, --row-hover, --line, --card, --soft, --ink, --ink-2, --ink-3, --ok, --bad, --rasp, --rasp-50, --cols.

Accessibility

  • ARIA table / row / columnheader / cell roles on a grid; checkboxes named "Select {name}" / "Select all"; rows open with Enter.

Found in the source

  • Roles in the markup: table, row, columnheader, presentation, cell.
  • ARIA attributes set: aria-hidden, aria-label, aria-sort.
  • Keys the code handles: Enter.

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

See also: MoneyNote · PersonCell · PlatformFollowers · StatusPill · Button · BulkBar · CopyLink · CreatorCell

Source

src/kit/patterns/RowList.tsx (line 122) on GitHub.

On this page