ListRow

When to useLink to "When to use"

• A list of things to open: each row is a button (onClick) or a link (href), with the open one marked active.
• Rows with their own commands: run, delete, a Menu of more, beside the row rather than inside it.
• Feeds that carry state: unread, dimmed (seen), and a tone rail for an error or a warning.

Use something else when:

• the list is static text with bullets, numbers or ticks: List
• the point is choosing a value: Select, RadioGroup or Combobox
• the entries nest: Tree
• there are thousands of rows: VirtualList
• it is the app's navigation: SideNav

UsageLink to "Usage"

import { IconButton, IconTile, ListRow, ListRows } from "@arshad-shah/cynosure";
import { alert, play, trash } from "@arshad-shah/cynosure/icons";

<ListRows label="Notifications" divided>
  {notifications.map((n) => (
    <ListRow
      key={n.id}
      label={n.message}
      description={n.source}
      trailing={n.time}
      leading={<IconTile icon={alert} size="sm" tone="danger" />}
      tone={n.level === "error" ? "danger" : undefined}
      unread={!n.read}
      dimmed={n.read}
      active={n.id === openId}
      onClick={() => open(n.id)}
      actions={
        <>
          <IconButton icon={play} label="Open" size="sm" variant="ghost" onClick={() => open(n.id)} />
          <IconButton icon={trash} label="Dismiss" size="sm" variant="ghost" onClick={() => dismiss(n.id)} />
        </>
      }
    />
  ))}
</ListRows>;

StatesLink to "States"

active draws an accent rail on the inline start and tints the row, and sets aria-current (page on a link row). unread makes the title bold and adds an accent dot. dimmed mutes the title and turns the leading slot grey; nothing is faded, so text in it (an avatar's initials) stays readable. tone draws a rail and a faint wash in that colour. The words "Unread" and the tone's name ("Error", "Warning", "Success", "Info") are read with the title; replace them through labels on ListRows, or set one to "" to read nothing.

Meta linesLink to "Meta lines"

description and detail sit under the title, smaller and muted; mono sets one of them in the monospace font (a connection string, a query). Every line is cut with an ellipsis; wrap lets the title wrap instead.

LinksLink to "Links"

With href the row is a link (through LinkBase: unsafe schemes such as javascript: are not linked).

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

The pattern is a list of buttons or links with a roving Tab stop, not a listbox: a listbox's options cannot hold the row's actions (ARIA allows no controls inside an option), and these rows open things rather than choose a value. The selected entry is marked with aria-current.

• Only the title is inside the row's button or link; its hit area covers the whole row, so a press on the leading slot, the text or the trailing slot lands on it. The button is named by the title (with the tone's word and "Unread") and described by the leading slot, the meta lines and the trailing slot.
• Actions are siblings of that button. The actions of the row holding the Tab stop are in the Tab order; other rows' actions are reached with Right. A row without onClick or href keeps its actions in the Tab order.
• Arrow keys inside a menu opened from the actions belong to the menu, and the actions stay shown while it is open.

TouchLink to "Touch"

Where the device has no hover, the actions are always shown, in their own place at the end of the row instead of over the trailing slot. Rows are at least 44px tall on a coarse pointer (24px otherwise), and IconButtons keep their own 44px hit areas.

ThemingLink to "Theming"

Tokens: --cy-list-row-background (set it to the colour of the surface the list sits on, so the actions cover the trailing slot cleanly), --cy-list-row-gap, --cy-list-row-padding-inline, --cy-list-row-rail-width, --cy-list-row-hover-mix, --cy-list-row-active-mix, --cy-list-row-wash-mix, --cy-list-row-meta-color, --cy-list-row-dimmed-filter, --cy-list-row-divider-color.

RelatedLink to "Related"

• List: static lists with markers.
• IconButton and Menu: row actions.
• IconTile, Avatar, Badge: leading and trailing content.
• VirtualList: very long lists.