Skip to Content
Which part for what

Lists

RowList and ListRow, for a list of things with one title each.

Use RowList with ListRow for a list of things. A table of columns is a DataTable, see Records.

Compact (default), one lineSecondary text follows the title on the same line. Actions show on hover, focus and selection.
Open the example ↗

Sizes

SettingRow height
density="compact", the default30px
density="comfortable"36px
lines={2} or lines={3}Rows with more text
On a phone44px for one line, 58px for two

A row of two or three lines has its title at 13/20 and its secondary text at 12/16, with 6px vertical padding. The time ends the first line, and the state ends the second.

Two and three linesFor rows that carry more, such as a pull request: the detail line is a MetaLine. Hairlines between rows with `divided`.
Open the example ↗

The parts of a row

In order:

  1. icon (16px) or leading (an Avatar size="sm"), in a fixed 20px box
  2. title
  3. secondary
  4. status, one State
  5. meta, a time or a count in text-3
  6. actions or persistentActions

actions are IconButton size="sm". They show on hover, focus and selection. On a phone or a touch screen they take no width, and are a left swipe and a long press menu away. persistentActions are always shown, such as answer buttons.

leadingActions and trailingActions are swipe actions. menu is the context menu.

Comfortable, with avatars
Open the example ↗
Persistent actionsAnswer controls that are the point of the row stay visible.
Open the example ↗

Columns line up

The rows of a RowList share one grid, each row a subgrid. Icons, titles, states, times and actions line up down the list.

The title keeps the width of the longest title, up to 40% of the row, before the trailing columns take theirs. The secondary text gives way first.

Long lists400 rows: RowList renders only what is in view once a list passes 150 rows; give it a height. Density is the list's. It still reorders: drag a row to the list's edge and it scrolls; the arrow keys, Page and Home and End move through every row.
Open the example ↗
Shared edgesEvery row is a ListRow: icons on one edge, titles on one edge, status and meta on one trailing edge.
Open the example ↗
Hand-built rowsThree modules, three row recipes: the icons, titles and trailing text each start somewhere else.
Open the example ↗

Row states

  • selected is the inset fill, bg-4, 6px from the edge of the list.
  • unread bolds the title and puts a dot at the leading edge of the row, inside the fill. In a list that tracks it, pass unread={false} on the read rows, so the column of the dot stays and nothing moves.
  • muted dims the row.
  • movable={false} pins a row in a list with onReorder.

No row has a grip or a delete button. You drag the row itself, and Delete is in its menu and on the Delete key.

The row is what movesNo grip and no delete button: press a row and move it to drag it (a press that does not move opens it), Alt and an arrow moves it from the keyboard, and Delete is in its context menu and on the Delete key, with Undo. On a touch screen a long press opens the menu, and moving the finger then picks the row up.
Open the example ↗
A grip and a delete button on every rowControls that repeat on every row: a grip to drag it by and a delete button beside its time. They crowd the row, put a destructive action one stray click away, and say what the row itself, its menu and the Delete key already do.
Open the example ↗
Selection is neutralSelected rows take the neutral fill and their checkboxes a neutral mark; the bar over the table is neutral too. The accent is left for what acts and what is new: buttons, links, the focus ring, unread dots.
Open the example ↗
Selection in the accentRows, checkboxes and the bar in the accent's tint: the selection outshouts the primary button and the unread dots, and a list with many rows selected turns into a block of colour.
Open the example ↗

With href or onClick the whole row is one link or button.

RowList items={…} renders only the visible rows past 150 rows. Give it a height. Its rows then take the widest trailing cell seen so far for each column.

divided adds hairlines between rows of several lines.

Variants

density and variant belong to the list.

VariantWhere
insetIn a card, panel or inspector at any depth. Titles sit on the text edge of the container, and the fill is 6px from its edge
inlineIn a property value or a form. 28px rows on the edge of the content
boxedA group of its own
Lists in an inspectorvariant="inset" fits a list into the card's padding wherever it sits in it: titles on the card's text edge, the selection fill 6px from its edge. variant="inline" puts a short list in a property's value, 28px rows on the value's edge.
Open the example ↗

Keys and gestures

The arrow keys, Home and End move between rows. The list is one tab stop.

With items and getKey a list can do more.

  • onReorder(from, to) moves rows. Drag the row itself past 4px, or on touch move it after the long press that opened its menu. Alt and an arrow key move it too. A line shows where it drops, and the list scrolls at its edges. The indices are those of items, so this works on long lists.
  • selectable lets the person select rows. A click opens, Cmd or Ctrl and a click toggles, and Shift and a click selects a range. Shift and an arrow key extend it. Space, Cmd or Ctrl and A, and Escape work as usual. A bar at the foot shows only while something is selected, with bulkActions.
  • onRemove removes rows, by the Delete key, Delete in the menu, or a swipe. Return an undo for a toast.
  • onAdd adds an add row.
  • editing is the iOS edit mode: a selection circle, then the content.
  • rowMenu is the context menu. It opens with a right click, the Menu key, Shift and F10, or a long press. The default items are Open, the row's actions, Rename and Delete.

On a row of a selection of several, the menu acts on the selection, with the bar's actions and "Delete 3". Any other row is selected alone first.

A row's onRename edits its title in place, by F2 or a double click. A row's children nest under it as a tree.

Reorder by drag or keyboardPress a row and move it to drag it (a press that does not move is a click); the line is where it lands, and the list scrolls at its edges. From the keyboard, Alt and an arrow on a row moves it, and the move is announced. On a touch screen, press and hold a row: its menu opens, and moving the finger picks the row up and closes the menu.
Open the example ↗
A list the person managesA click opens a row; Cmd or Ctrl and a click adds it to the selection, Shift and a click selects the range, Shift and an arrow extends it, Space toggles the focused row, Cmd or Ctrl+A selects all and Escape clears. The bar at the foot appears only while something is selected. Drag a row to move it. Delete removes the focused row (or the selection) with Undo, and so does Delete in its menu; F2 or a double click renames.
Open the example ↗
A menu for the row, or for the selectionRight-click a row, press the Menu key or Shift+F10 on it, or long-press it on a touch screen. Select two or three rows first (Cmd or Ctrl, or Shift, and a click) and right-click one of them: the menu acts on all of them. A row outside the selection is selected alone first, as in a file manager.
Open the example ↗
The menu acts on the selectionThree rows are selected; a right click on any of them opens a menu that says what it acts on: “3 selected”, Archive 3, Delete 3. A right click outside the selection selects that row alone first.
Open the example ↗
A menu that ignores the selectionThree rows are selected, but the right-clicked row's menu says Archive and Delete for that row alone: the person cannot tell whether Delete takes one row or three.
Open the example ↗
A bar while something is selectedNothing about selection shows until a row is selected; then the count and what can be done with it, at the list's foot.
Open the example ↗
A toolbar that is always thereA row of disabled bulk buttons and a checkbox on every row, for a selection nobody has made: chrome for the rare case, taking room in the normal one.
Open the example ↗
Nested rowsRows given children are a tree: each level is indented, the disclosure (or Right and Left) shows and hides the rows under it, and the trailing columns stay the list's, so the values of every level line up.
Open the example ↗
Contextual actions on a phoneThe hover actions take no width on a touch screen: swipe a row to the left to reveal them, or press and hold it for a menu of them. Swipe the first row to the right to mark it read. Answer buttons (persistentActions) stay visible.
Open the example ↗
Editing a list on a phoneAs on iOS: Edit puts a selection circle at each row's start, and the bar at the foot acts on the selection. Press and hold a row for its menu and move the finger to drag it; swipe it to the left to delete it.
Open the example ↗
List row in the gallery ↗
Edit on GitHub

Last updated on

On this page