List

A flat set that states its order, its size and what a bulk action would act on.

Overview

A list is read as a claim whether or not one was intended: position reads as priority, and a count with no denominator reads as the whole set. Most of this page is about closing the gap between what a list shows and what a clinician concludes from it.

Depth is a different component. Tree was documented here and shipped under this install command; a product with a flat worklist has no use for one.

Anatomy

Order and completeness

• Never sort by relevance, confidence or model score without saying so and offering the underlying deterministic order. See Confidence & uncertainty.
• Never truncate silently. "Showing 10 of 34" with a control to see the rest, or show all 34. A list that stops at ten with no indication has hidden twenty-four things.
• Never reorder under the reader. New items arriving while the list is on screen are appended and marked, not slotted in — the same rule as Data grid.
• Empty is not blank. An empty list states which of "none exist", "none match the filter" and "could not load" applies — see Empty state.
• Filtered lists carry their filters visibly as removable tags — see Filter.

Selecting from a list

A list whose items can be chosen is a different component from a list that is read, and it carries a failure the reading kind does not: the selection and the visible set can drift apart. Everything below follows from that.

Select all, of what?

Selection outliving what is visible

Three items are selected. The clinician narrows the filter and two of them drop out of view. Are they still selected? In most implementations yes, invisibly — so "export selected" then produces three files when one is on screen.

• The selected count is always visible, whether or not any selected item is: "3 selected · 1 shown". The gap between those two numbers is the whole hazard, so it is rendered rather than left to be discovered.
• The selected set is reachable in one action — a control that shows just the selected items. A count nobody can expand is a number the clinician has to trust.
• Any action names what it will act on, in the confirmation, by count and by scope: "Export 3 selected patients, 2 of which are not currently shown." The confirmation is where the drift gets caught, and it is the last chance.
• Changing the filter never silently drops a selection. If the component does clear hidden selections, it says so as it happens; if it keeps them, it says that too.

What selection may never be used for

Acknowledge & escalate forbids bulk acknowledgement in any form — not as a toolbar action, not behind a setting. Multi-select is the most natural way to build one, so the boundary is stated here too.

The test is whether the action asserts something about each item individually. If it does, the clinician performs it individually — see Editing the draft, where the same argument settles what a single acceptance can honestly cover.

Locked and unavailable items

• A locked item says why, in the row. The usual pattern puts the reason in a tooltip on hover; that reason does not exist on a touch cart, and an option that cannot be chosen for an unstated reason reads as a fault.
• Locked is not hidden. An item the clinician may not select is still an item they need to know exists — removing it changes the set they believe they are looking at.
• Select-all skips locked items and says how many it skipped. Silently selecting fewer than "all" is the same class of error as the filtered count above.

Order, and rearranging by hand

• Sorting a list with a selection preserves the selection and states it. Items moving is expected; the set the clinician assembled is not something a re-sort edits.
• Manual reordering is available only where order is the clinician's to set — an order set they are composing, a print sequence. Never in a list whose order is a clinical statement, per Order and completeness.
• Where reordering exists, it is not drag-only. Move-up and move-down controls on each row, per SC 2.5.7 — and they work on a cart, where dragging a row while the trolley moves is how items land in the wrong place.

States

What the component enforces, and what it only asks for

The header holds the counting rules. The list holds almost nothing else, because what a list is showing and in what order is entirely what you passed it.

Do's and don'ts

The pair about a collapsed branch declaring its contents moved to Tree.

Accessibility

• A real <ul>/<li> so the set size is announced. A stack of divs tells a screen-reader user nothing about how many items exist.
• The order statement and count are inside the list's labelled region, so they are reachable in the same breath as the items rather than orphaned above it.
• aria-current for the selected item, alongside fill and an inset rule. Three signals, one non-visual.
• Trees use role="tree", treeitem and group, with aria-expanded, aria-level, aria-setsize and aria-posinset.
• A nested list is a Tree, with its own keyboard model — one tab stop, arrows that move and expand. A flat list has no such model and needs none: its rows are reached with Tab.
• Branch state is in the accessible name — "Laboratory, 6 items, 1 critical, collapsed" — not only in a coloured chip.
• Rows are not link-in-link. A clickable row containing its own buttons is two overlapping targets; either the row navigates or the buttons act, never both in the same pixel.
• Targets ≥ 24 px including the tree's expand affordance, which is the one most often built at 12 (WCAG 2.2 SC 2.5.8).
• Reflow to 320 px — list items stack their secondary line, and tree indentation caps so deep levels do not push content off-screen (SC 1.4.10).

Outcomes of use

What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.

• Effectiveness — the clinician knows the set is complete, or knows exactly how it is not. Nothing relevant is behind an unmarked collapse.
• Efficiency — the secondary line answers the question most items are opened to answer, so most items do not need opening.
• Satisfaction — an order that can be checked. Trust in a list is almost entirely trust in its ordering.

Clinical safety notes

• Order stated in words. (you) Mitigates: position read as clinical priority.
• Count shown as n of N. (the component) Mitigates: a filtered subset read as the whole record.
• No silent truncation. (the component) Mitigates: relevant items existing beyond an invisible cut-off.
• Collapsed branches report contained state. (you) Mitigates: a critical result concealed by a closed node.
• Degraded items stay in the set with their state named. (you) Mitigates: a recording believed not to exist because its analysis failed.
• No reordering under the reader. (you) Mitigates: opening the wrong item because the row moved between look and click.
• Absolute timestamps. (you) Mitigates: a relative time going stale on an unattended screen.
• Empty states distinguish none-exist from none-match from failed-to-load. (you) Mitigates: a load failure read as an absence of findings.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/list.json

<SelectionHeader
  selectedCount={2} selectedShown={1}
  shownCount={4} totalCount={19}   // both required: "4 of 19", never a bare 4
  onSelectShown={selectShown} onSelectAll={selectAll}
/>
<List label="Recordings this encounter">
  <ListItem primary="12-lead ECG" secondary="ST elevation V2–V4"
    meta="15:41:02" />
</List>

Related

• Tree — the same set when the hierarchy is the point.
• Data grid — when the items have columns worth comparing.
• Filter — what is hiding the rest of the set.
• Empty state — a list with nothing in it, and why that is not one thing.