# List _Box Kite 2.2.4 · a markdown copy of https://www.box-kite.dev/list/_ A list of things to read and pick from: rows of leading media, text and trailing values, one action covering each item — and not a line of JavaScript, so it renders on a server. **Import** ```jsx import List from '@box-kite/react/components/list'; ``` **Usage** ```jsx {people.map((person) => ( {person.initials} {person.name} {person.time} {person.text} ))} ``` ## An item is a row, and its content is rows A `List.Item` is a flex row of three slots: `List.Media` leading, `List.Content` taking the room, `List.End` trailing. The content is a column, and each line of it is a `List.Row` — its parts side by side, the first taking the room and the last pushed to the end, so a title and its time, or a status and a count, line up down the list. Every part is optional, and an item with none of them is simply a flex row of whatever it holds. One line, two or three A title alone is one line; a `List.Description` under it is two; a `List.Overline` above it, or a description clamped at two lines, is three. That is Material's whole taxonomy, and it falls out of which parts are there. Text stops where you say `lines={1}` ends a title or a description in an ellipsis, `2` and `3` clamp it. Unset it wraps, which is right for a name whose end matters as much as its start. ## A main row and a secondary one `secondary` makes a row the quieter line under the main one — smaller and muted — which is the shape of a mail client, an order list or a pull-request queue: what it is and when on top, its state and its numbers below. ```jsx Order 4182 · Grace Hopper 2 min ago Paid · 3 items €42.00 ``` ## A row that wraps A row keeps to one line and squeezes its parts, which is what a title and a time want. `wrap` lets the parts go onto a new line instead and starts them all at the start — a set of tags, a list of labels — and on `List.Item` it lets the slots themselves wrap, so a trailing control drops under the text on a narrow screen rather than crushing it. ```jsx Design review {['design', 'research', 'mobile', 'accessibility', 'typography', 'q4', 'roadmap'].map((tag) => ( {tag} ))} ``` ## Leading and trailing `List.Media` takes three shapes as variants — `icon` (a tinted square), `avatar` (a circle that clips) and `image` (a larger thumbnail) — or none, for a bare icon. `List.End` stacks a value and its label and aligns them to the end, in tabular figures, so the numbers in a column of items line up. A `chevron` on the item says that pressing it goes somewhere with more. ```jsx Wi-Fi Home 5G Server · eu-west api-04 Healthy for 41 days 99.98% Uptime ``` ## One action covers the item `List.Action` goes in the title, and its `::after` stretches over the whole item — so the whole row presses, the focus ring draws round the whole row, and the name a reader hears is the title alone rather than every value in it. What it is follows from what it is given: an `href` makes it a link, an `htmlFor` makes it the label of a checkbox (a press anywhere on the item ticks it), and neither makes it a button. A control of the item's own goes in List.Actions A switch, a menu, a second button: `List.Actions` lifts them above the covering action, so they take their own presses. Anything outside it — media, text, the end values — presses the action. A pressable item says so without a prop The hover, pressed, current (`aria-current`) and disabled states are read off the action with `:has()`, so an item with no action is plain text and one with an action looks pressable — nothing to keep in step. ```jsx {people.map((person) => ( toggle(person.id)} /> {person.name} ))} Notifications ``` ## Four looks, three sizes Dividers are the default — the right look for a long list of things of one kind, where a frame round every item is noise. `variant="plain"` drops them, `"card"` frames the whole list as one block (the settings screen), and `"separated"` frames each item on its own with a gap between. An item's `size` is `sm` (44px, still a finger's width), `md` (56px) or `lg` (72px). ```jsx … ``` ## Labelled values `List.Fields` is a `
` of `List.Field`s, each a label over its value, as many to a line as fit at 8rem — two on a phone. Every value keeps its label for a screen reader as well as for the eye, which a row of bare values does not. ```jsx Order 4182 Grace Hopper €42.00Total Paid 3 15 Oct Tomorrow ``` ## Groups, and a label that sticks `List.Group` is an item holding its label and a list of its own, so a reader hears the label and then "list, 3 items". `level` makes the label a heading to jump between; `sticky` keeps it at the top of the screen while its items scroll under it, until the next group's label pushes it off — set `vars={{ 'list-sticky-top': '4rem' }}` on the list to clear an app's own header. ```jsx … … ``` ## Swipe an item for its commands `SwipeItem` (`@box-kite/react/components/swipeItem`) is a `List.Item` whose row slides along the line while a tray of `SwipeItem.Action`s opens in the space it leaves — `startActions` under the start edge, `endActions` under the end, the first of each outermost. Past half open it opens, short of it it closes, and a flick goes the way it was going; with `fullSwipe`, carrying it most of the way across performs the outermost action. Nothing is drawn under the row, so it keeps whatever the list paints. Try it with a finger, a pen or a mouse — or Tab to the actions, which opens the tray they are in. ```jsx Pin} endActions={ <> Delete Snooze } > Ada Lovelace ``` A swipe is a shortcut, not the only way in The actions are real buttons in the tab order, and focus reaching one opens its tray. A path-based gesture still wants a way in for a pointer that cannot drag: put the same commands on the item's own page, or in a `Menu` in `List.Actions`. An open item closes before it opens A press on an open item closes it rather than following its action, and a press anywhere else closes it too — the press was most likely aimed at the tray. ## Put the items in order by hand `SortableList` (`@box-kite/react/components/sortableList`) is a `List` whose items are dragged by a `SortableList.Handle`. The app owns the order: `onOrderChange` reports it as the items' `value`s, and the list draws whatever order it is rendered in. During a drag nothing is reordered — the item follows the pointer and its neighbours step aside — and the order changes once, on the drop, which glides into place. `onOrderCommit` is the one to save. ```jsx setIds(order)}> {ids.map((id) => ( {names[id]} ))} ``` The keyboard gets a grab Enter or Space on a handle picks the item up, the arrows move it, Enter drops it and Escape puts it back — every step announced in a live region. Or press, then press where it goes A press on a handle that does not drag picks the item up too, and a press on another item then drops it there: the way to reorder with a pointer that cannot drag. ## A list too long to render whole `VirtualList` (`@box-kite/react/components/virtualList`) renders the items near the screen and makes the rest space. Each item drawn is measured and kept by its `itemKey`, so items of different heights mix; one not drawn yet counts as the mean of those that have been, and the list holds its height while it scrolls, so a dragged scrollbar thumb stays under the pointer. The scroller is found rather than declared — the nearest one that scrolls, or the page — and each item carries `aria-setsize` and `aria-posinset`, so a reader hears "12 of 10,000". `onRangeChange` is where an endless list fetches its next page. ```jsx message.id}> {(message) => ( {message.subject} {message.text} )} ``` ## What a reader hears A `