Data

Which component to use for figures, tables, charts, lists of records, or history. Find the job, take the component, and read the “not when” before you commit: it names the thing people reach for by mistake, and what to use instead.

At a glance

Job	Use	Not when	Instead	Because
Put a face or initials beside a person's name	`Avatar`	The avatar would be the only place the person is named	`Item`	A name is text; put the avatar in an item's `lead` beside the name rather than instead of it.
		The mark stands for a system or an integration, not a person	`Connection`	A connection has its own mark and says its state in words.
		It shows who did a run of actions in order	`Feed`	A feed groups each person's run of actions and takes the avatar as the group's mark.
Compare amounts across categories on a zero baseline	`BarChart`	Change over time is the point	`LineChart`	A line shows trend and may float off zero; bars must sit on zero.
		A direction beside a figure, with no axis	`Sparkline`	A sparkline is a shape, not a measurement.
		Two measures on different scales	`ChartFrame`	Never a second axis: draw two charts, or index both to a common base.
		Presence or absence at each crossing of two lists	`Matrix`	Coverage is a grid of marks, not a quantity.
		One or a few headline figures	`Stat`	A chart of three bars is a row of figures with extra ink.
Show how one or more measures change over time	`LineChart`	Comparing amounts between categories	`BarChart`	Categories are not a continuum; a line between them implies one.
		The trend only needs a glance beside a figure	`Sparkline`	A sparkline is the shape without axes, legend or tooltip.
		Two measures of different scale	`ChartFrame`	One y-axis always: two charts in two frames, or index both to a common base.
Show which way a figure has been moving, beside the figure	`Sparkline`	The reader needs to read values off it	`LineChart`	A sparkline has no axes, no legend and no tooltip.
Show which way a figure has been moving, beside the figure	`Sparkline`	There is no figure beside it	`Stat`	A shape alone says nothing about how much; give it the number it qualifies.
Frame a chart with its title, legend, plot and a table view	`ChartFrame`	Bars or lines	`BarChart`	`BarChart` and `LineChart` already render inside the frame.
Frame a chart with its title, legend, plot and a table view	`ChartFrame`	The data is better read as a table than seen as a shape	`Table`	A chart earns its place by showing a shape; exact lookups belong in a table.
Set out a proposition somebody has to adjudicate — the assertion, the argument, where it stands	`Claim`	The rows are records with a name, not sentences to judge	`Item`	An item is a one-line title and provenance; a claim is prose with a case attached.
		An agent proposes a change that will be written on a yes	`ConfirmCard`	A confirm card shows the values it will write and stays as the record of the answer.
		It is an authored note about something, in a thread	`Comment`	A comment is a note with an author and a time; nothing is adjudicated.
Show authored notes about a thing, and a place to write the next one	`Comment`	The record is what people did, not what they wrote	`Feed`	A feed groups each person's actions in order.
		A person is talking with an agent that answers	`Conversation`	A conversation is two-sided and live, and announces turns as they arrive.
		It is a record of what people said, to work through	`Transcript`	A transcript turn is part of a continuous exchange, timed against a recording.
List the properties of one thing as names and values	`DescriptionList`	The values add up to a total	`Summary`	A summary is term/value pairs with one emphasised total row.
		Several records are compared on the same properties	`Table`	A table puts one record per row so values compare down a column.
		A few headline figures summarise a page	`Stat`	A stat is a figure set large with its label and delta; a description list is quiet reference.
Show who did what, in order, with each person's run of actions kept together	`Feed`	The events have nobody in them	`Timeline`	A timeline is a chronology of events; a feed is a sequence of people.
		People discuss the thing in their own words	`Comment`	A comment is an authored note with a composer; a feed records actions.
		It is an exchange of what people said in an interview or meeting	`Transcript`	A transcript is a record of speech somebody works from, with times into a recording.
Let people key values into many rows at a sitting	`GridTable`	The rows are read, compared or sorted, not typed into	`Table`	A table presents what a system holds; a grid is a keying surface.
		One record with a handful of fields	`Field`	A form of labelled fields reads better than a one-row grid.
		Marking which rows cover which columns	`Matrix`	A matrix records presence on a grid; a grid table records typed values.
List API keys by name and fingerprint, with their scopes, last use and expiry	`KeyList`	The person needs the secret value itself, to copy	`Credential`	A key row never holds the secret; a credential does, masked, with copy.
		The rows are general records that are not keys	`Item`	An item is the general record row — a title, a line of provenance, marks at the end.
		The values are compared down columns or sorted	`Table`	A table is for values you compare down a column, with sort.
Show an event rule as a sentence — when this happens there, do that here	`Rule`	The steps are a sequence a person goes through	`Stepper`	A stepper is a position in a sequence; a rule is one trigger and one action.
		The relationships are many-to-many and need a picture	`LayeredGraph`	A layered graph draws what covers what across layers; a rule is a single sentence.
		The endpoint is a code sample to copy	`CodeBlock`	A code block carries a copy control and a language; `Endpoint` is a method and a URL.
List records, each read on its own — a name, where it came from, a mark or two	`Item`	Values are compared down a column or sorted	`Table`	A table is for values you compare down a column.
		The rows are files	`DocList`	A document list carries the file type badge, size and the list/grid views a library needs.
		Each row is an assertion in prose that somebody has to adjudicate	`Claim`	An item's title is one line that never wraps; a claim holds a measured sentence, its argument and its standing.
		The list is a long column the reader scrolls past beside the main view	`Dock`	A dock gives momentary width to whatever is at the focus point of a narrow column.
Explore how a large set of things nobody arranged relate to each other	`KnowledgeGraph`	The nodes have an order the reader already knows — layers, then a sequence	`LayeredGraph`	A layered graph is laid out, not simulated, and its nodes are real buttons in lists.
		The question is which of these covers which of those	`Matrix`	A matrix shows presence and absence on a grid, read across a row and down a column.
		The structure is a hierarchy	`Tree`	A tree has one parent per node and a keyboard contract for expanding and collapsing.
Show what covers what across ordered layers, and what nothing covers	`LayeredGraph`	The set is large and has no order — a corpus of linked things	`KnowledgeGraph`	The knowledge graph is force-directed on a canvas and built to hold a thousand nodes.
		The reader needs every pairing, present or absent, at once	`Matrix`	A matrix shows each cell of rows against columns; a layered graph shows only the lines that exist.
		It is one trigger leading to one action	`Rule`	A rule is one sentence, not a graph.
List files and folders in a document library	`DocList`	The rows are records that are not files	`Item`	An item is the general record row; a doc row carries a type badge and file size.
		Files are compared on several columns, or sorted	`Table`	A table sorts and compares down columns.
		The files are attachments the person is uploading	`FileUpload`	A file upload has the drop zone over a real file input and the list of what was added.
		The files nest several levels deep	`Tree`	A tree expands and collapses a hierarchy with one Tab stop.
Show which things cover which, read across a row and down a column	`Matrix`	The cells hold values to compare, not presence and absence	`Table`	A table is records down a column; a matrix is a yes-or-no at every crossing.
		The coverage runs through ordered layers — requirements, then milestones, then outcomes	`LayeredGraph`	The layered graph keeps the order and draws what covers what as lines and words.
		A single level against a target	`Meter`	A meter is one figure on a track; a matrix is many crossings.
		A set of verdicts on one row that do not agree	`Tally`	A tally sums the disagreement in one bar with the counts as words.
Show a level that is simply true, against its scale and target	`Meter`	A task advancing toward done	`Progress`	`role="progressbar"` means work under way; a meter means a level, and swapping them misreports what is happening.
		Several verdicts on one thing that do not agree	`Tally`	A tally shows the split with the counts as words; one tone would hide the disagreement.
		The number alone carries it, with no scale	`Stat`	A stat is a figure and a label; a track with no meaningful maximum is decoration.
		Comparing the level across many categories	`BarChart`	Bars on a shared zero compare; a stack of meters does not.
Show a headline figure with its label and what changed	`Stat`	The figure is a level against a scale or a target	`Meter`	A meter draws the level on a track and says the target in words; a stat is just the number.
		The shape over time matters more than the latest value	`LineChart`	A trend needs a line with axes; put a `Sparkline` beside a stat when direction is enough.
		Many categories compared by size	`BarChart`	A row of more than four or five stats is a chart that lost its axis.
		Label and value pairs that describe one thing, not measure it	`DescriptionList`	Attributes are terms and values in body type; a stat is a figure set large.
		Totals that add up to a price	`Summary`	A summary is term and value rows with one emphasised total.
Add lines up to a total the eye lands on	`Summary`	The pairs are properties of a record and nothing adds up	`DescriptionList`	A description list is plain names and values with no total.
		The figures are headline measures, not a sum	`Stat`	A stat row is figures that read as one sentence; a summary is a sum.
		Many line items are compared or sorted	`Table`	A table compares rows down columns; a summary is a short stack ending in a total.
Show records whose values are compared down a column	`Table`	People type values into the cells	`GridTable`	A grid has a spreadsheet's keyboard, owned columns and type-ahead per column; a table is read.
		The question is which row covers which column — presence and absence on a grid	`Matrix`	A matrix is one Tab stop with arrow keys, pinned headings, and a mark in every tinted cell.
		Each row is read on its own and most columns would be empty	`Item`	A list of records is a name, a line of provenance and a mark or two; empty columns are noise.
		A list of files	`DocList`	The library rows carry type badges, size and a preview pane.
		A handful of label and value pairs about one thing	`DescriptionList`	One record's attributes are terms and values, not rows.
Page through a long table and say which rows are on show	`TablePager`	The table fits on one page	`Table`	The pager renders nothing then — a "page 1 of 1" control does nothing.
		Paging something that is not a table — search results, a gallery	`Pagination`	Pagination is the bare page list; the table pager adds the range and is wired to `usePagedTable`.
		Stepping one item at a time through a set, inside a pane	`PagerChip`	The chip says "4 of 19" with previous and next; it is not a page list.
Show what a set of statements adds up to when they do not agree	`Tally`	One value with one tone	`Meter`	A meter is a single level; a tally is a split.
		Nobody has said anything yet	`State`	A tally with every part at zero renders nothing; say the absence in your own words.
		Parts of a whole across categories, compared between rows	`BarChart`	A stacked bar chart has a shared axis and a legend for many rows.
		One settled status	`Tag`	A single verdict is a status word.
Show events in the order they happened	`Timeline`	The history is people doing things, several in a row each	`Feed`	A feed groups each person's run of actions so the boundaries between people are seen, not read.
		People write notes about the thing and reply	`Comment`	A comment is an authored note with a composer; a timeline entry is an event.
		The steps are a process the person is part-way through	`Stepper`	A stepper shows position in a sequence still to finish; a timeline records what already happened.

`Avatar`

Put a face or initials beside a person's name.

Use when

Beside the name it depicts — in a comment, a feed group, a header menu. It is decorative there and hidden from assistive tech.
A stack of people on one thing: AvatarGroup.
Standing alone with no name beside it: pass aria-label so it has one.

Not when

The avatar would be the only place the person is named → Item. A name is text; put the avatar in an item's lead beside the name rather than instead of it.
The mark stands for a system or an integration, not a person → Connection. A connection has its own mark and says its state in words.
It shows who did a run of actions in order → Feed. A feed groups each person's run of actions and takes the avatar as the group's mark.

Confused with Item, Feed, CommentReact Avatar AvatarGroupClasses .avatar

See it on the demo page

`BarChart`

Compare amounts across categories on a zero baseline.

Use when

Sizes side by side — per team, per month, per category; stacked for parts of each whole.
orientation="horizontal" for long category names, a ranking, or a phone: the name above each bar, the figure at its end.
Up to eight series in the fixed palette order; a ninth folds into "Other".

Not when

Change over time is the point → LineChart. A line shows trend and may float off zero; bars must sit on zero.
A direction beside a figure, with no axis → Sparkline. A sparkline is a shape, not a measurement.
Two measures on different scales → ChartFrame. Never a second axis: draw two charts, or index both to a common base.
Presence or absence at each crossing of two lists → Matrix. Coverage is a grid of marks, not a quantity.
One or a few headline figures → Stat. A chart of three bars is a row of figures with extra ink.

Confused with LineChart, Stat, Meter, Matrix, ChartFrameReact BarChartClasses .chart-bar .chart-hbar .chart-hbars

See it on the demo page

`LineChart`

Show how one or more measures change over time.

Use when

A trend across dates, with a crosshair and a shared tooltip.
Several series of the same unit on one y-axis, in the fixed palette order.

Not when

Comparing amounts between categories → BarChart. Categories are not a continuum; a line between them implies one.
The trend only needs a glance beside a figure → Sparkline. A sparkline is the shape without axes, legend or tooltip.
Two measures of different scale → ChartFrame. One y-axis always: two charts in two frames, or index both to a common base.

Confused with BarChart, Sparkline, StatReact LineChartClasses .chart-line

See it on the demo page

`Sparkline`

Show which way a figure has been moving, beside the figure.

Use when

Next to a Stat or in a table cell, where direction matters and the exact values do not.
Always with a text label — it shows direction, not magnitude.

Not when

The reader needs to read values off it → LineChart. A sparkline has no axes, no legend and no tooltip.
There is no figure beside it → Stat. A shape alone says nothing about how much; give it the number it qualifies.

Confused with LineChart, StatReact SparklineClasses .sparkline

See it on the demo page

`ChartFrame`

Frame a chart with its title, legend, plot and a table view.

Use when

Wrapping a chart form the system does not ship, so it still has a title, a legend and the data as a table.
Anywhere a chart appears: the table view is the relief for series colours under 3:1, and makes the numbers copyable.

Not when

Bars or lines → BarChart. BarChart and LineChart already render inside the frame.
The data is better read as a table than seen as a shape → Table. A chart earns its place by showing a shape; exact lookups belong in a table.

Confused with BarChart, LineChart, TableReact ChartFrameHooks linear ticks extent seriesColor fmt MAX_SERIESClasses .chart

See it on the demo page

`Claim`

Set out a proposition somebody has to adjudicate — the assertion, the argument, where it stands.

Use when

A finding, a held-open decision, or a reading a machine proposed and a person has not confirmed.
The argument has an author (ClaimReason by), because whether a machine or a person wrote it is the first thing a reader needs.
Where it stands is said once (ClaimStanding), with the controls level with the first line; settled once it is decided.

Not when

The rows are records with a name, not sentences to judge → Item. An item is a one-line title and provenance; a claim is prose with a case attached.
An agent proposes a change that will be written on a yes → ConfirmCard. A confirm card shows the values it will write and stays as the record of the answer.
It is an authored note about something, in a thread → Comment. A comment is a note with an author and a time; nothing is adjudicated.

Confused with Item, ConfirmCard, Comment, CalloutReact Claim ClaimActions ClaimBody ClaimReason ClaimStanding ClaimTextClasses .claim

No demo page yet.

`Comment`

Show authored notes about a thing, and a place to write the next one.

Use when

An activity thread on a work item: each note with its author, a time and the text.
The composer under the thread (CommentCompose) with its actions (CommentActions).

Not when

The record is what people did, not what they wrote → Feed. A feed groups each person's actions in order.
A person is talking with an agent that answers → Conversation. A conversation is two-sided and live, and announces turns as they arrive.
It is a record of what people said, to work through → Transcript. A transcript turn is part of a continuous exchange, timed against a recording.

Confused with Feed, Conversation, Transcript, TimelineReact Comment CommentCompose CommentActionsClasses .comment

See it on the template

`DescriptionList`

List the properties of one thing as names and values.

Use when

The details of a record — Owner, Created, Status, Due — each a term and its value, as a real <dl>.
A narrow column or a side pane: stacked puts the term above the value.

Not when

The values add up to a total → Summary. A summary is term/value pairs with one emphasised total row.
Several records are compared on the same properties → Table. A table puts one record per row so values compare down a column.
A few headline figures summarise a page → Stat. A stat is a figure set large with its label and delta; a description list is quiet reference.

Confused with Summary, Table, StatReact DescriptionListClasses .dl

See it on the demo page

`Feed`

Show who did what, in order, with each person's run of actions kept together.

Use when

An activity record: one person opened three findings, then another answered two of them — a FeedGroup per actor, a FeedItem per action.
An ordered list of groups, so a screen reader announces "3 of 5" without anything written for it.

Not when

The events have nobody in them → Timeline. A timeline is a chronology of events; a feed is a sequence of people.
People discuss the thing in their own words → Comment. A comment is an authored note with a composer; a feed records actions.
It is an exchange of what people said in an interview or meeting → Transcript. A transcript is a record of speech somebody works from, with times into a recording.

Confused with Timeline, Comment, Transcript, ItemReact Feed FeedGroup FeedItemClasses .feed

See it on the demo page

`GridTable`

Let people key values into many rows at a sitting.

Use when

The rows and keys exist and people must fill in facts only they hold — two hundred rows of owners, codes or names.
Some columns are filled by people and some come from a source: mark the owned ones with GridHead.
Show how far the filling has got with GridProgress.

Not when

The rows are read, compared or sorted, not typed into → Table. A table presents what a system holds; a grid is a keying surface.
One record with a handful of fields → Field. A form of labelled fields reads better than a one-row grid.
Marking which rows cover which columns → Matrix. A matrix records presence on a grid; a grid table records typed values.

Confused with Table, Matrix, InputReact GridTable GridHead GridCell GridProgressClasses .grid-table .grid-cell .grid-head-owned .grid-progress

See it on the demo page

`KeyList`

List API keys by name and fingerprint, with their scopes, last use and expiry.

Use when

Managing API keys: each KeyRow shows a name, a fingerprint that identifies without exposing, scopes and when it was last used.
Scopes as Scopes / Scope; mark write on the one that can change something so it is the one that stands out.
Expiry: expiring is a warning because it still works today; only expired is an error.

Not when

The person needs the secret value itself, to copy → Credential. A key row never holds the secret; a credential does, masked, with copy.
The rows are general records that are not keys → Item. An item is the general record row — a title, a line of provenance, marks at the end.
The values are compared down columns or sorted → Table. A table is for values you compare down a column, with sort.

Confused with Credential, Item, TableReact KeyList KeyRow Scopes ScopeClasses .key-list .key-row .scopes .scope

See it on the demo page

`Rule`

Show an event rule as a sentence — when this happens there, do that here.

Use when

An automation or event rule: a trigger and its event, an arrow, then the target and its action; enabled={false} shows it off.
An inbound webhook address with its method — Endpoint, in mono.

Not when

The steps are a sequence a person goes through → Stepper. A stepper is a position in a sequence; a rule is one trigger and one action.
The relationships are many-to-many and need a picture → LayeredGraph. A layered graph draws what covers what across layers; a rule is a single sentence.
The endpoint is a code sample to copy → CodeBlock. A code block carries a copy control and a language; Endpoint is a method and a URL.

Confused with Connection, CodeBlock, ItemReact Rule EndpointClasses .rule .endpoint

See it on the demo page

`Item`

List records, each read on its own — a name, where it came from, a mark or two.

Use when

A list of notes, actions or entries: a one-line title, a quieter line of provenance (meta), and tags or a button on the title's line (trailing).
Rows where table columns would be empty most of the time.
An icon or avatar before the text (lead) and more detail under the meta.

Not when

Values are compared down a column or sorted → Table. A table is for values you compare down a column.
The rows are files → DocList. A document list carries the file type badge, size and the list/grid views a library needs.
Each row is an assertion in prose that somebody has to adjudicate → Claim. An item's title is one line that never wraps; a claim holds a measured sentence, its argument and its standing.
The list is a long column the reader scrolls past beside the main view → Dock. A dock gives momentary width to whatever is at the focus point of a narrow column.

Confused with Table, DocList, Claim, Dock, FeedReact Item ItemListClasses .item

No demo page yet.

`KnowledgeGraph`

Explore how a large set of things nobody arranged relate to each other.

Use when

A corpus of entities and links — hundreds to a thousand nodes — laid out by force on a canvas.
The kinds are the caller's own words, coloured from the series palette in declared order; eight at most.
Always paired with a real list of the entities and their relationships, because a canvas cannot be traversed.

Not when

The nodes have an order the reader already knows — layers, then a sequence → LayeredGraph. A layered graph is laid out, not simulated, and its nodes are real buttons in lists.
The question is which of these covers which of those → Matrix. A matrix shows presence and absence on a grid, read across a row and down a column.
The structure is a hierarchy → Tree. A tree has one parent per node and a keyboard contract for expanding and collapsing.

Confused with LayeredGraph, Matrix, TreeReact KnowledgeGraphHooks createLayout tick settle bounds radiusForClasses .graph

See it on the demo page

`LayeredGraph`

Show what covers what across ordered layers, and what nothing covers.

Use when

Layers read left to right — requirements, then milestones in sequence, then where the sequence ends — with a line for each cover.
Uncovered nodes need to be brought forward, and a person may move one under another (drag, or A then Enter by keyboard).
A narrow pane: below 30rem of its own width the layers stack and the lines become words.

Not when

The set is large and has no order — a corpus of linked things → KnowledgeGraph. The knowledge graph is force-directed on a canvas and built to hold a thousand nodes.
The reader needs every pairing, present or absent, at once → Matrix. A matrix shows each cell of rows against columns; a layered graph shows only the lines that exist.
It is one trigger leading to one action → Rule. A rule is one sentence, not a graph.

Confused with KnowledgeGraph, Matrix, TreeReact LayeredGraphHooks layoutGraph edgePath uncoveredIds layerNodesClasses .layered-graph

See it on the demo page

`DocList`

List files and folders in a document library.

Use when

A library of files as rows (DocList / DocRow) or as cards (DocGrid / DocCard).
File type is a mono badge (DocType) from the extension, never a coloured chip; folders are the one exception.

Not when

The rows are records that are not files → Item. An item is the general record row; a doc row carries a type badge and file size.
Files are compared on several columns, or sorted → Table. A table sorts and compares down columns.
The files are attachments the person is uploading → FileUpload. A file upload has the drop zone over a real file input and the list of what was added.
The files nest several levels deep → Tree. A tree expands and collapses a hierarchy with one Tab stop.

Confused with Item, Table, FileUpload, DocPreview, TreeReact DocType DocList DocRow DocGrid DocCardHooks kindOf formatBytesClasses .doc-list .doc-row .doc-type .doc-grid .doc-card

See it on the demo page

`Matrix`

Show which things cover which, read across a row and down a column.

Use when

Coverage on a grid — requirements against tests, controls against systems, people against projects.
Grids wider than the screen: it scrolls in its own frame with headings and row labels pinned, and the cells are one Tab stop.
Totals per row or column; a tone on a cell always comes with a mark.

Not when

The cells hold values to compare, not presence and absence → Table. A table is records down a column; a matrix is a yes-or-no at every crossing.
The coverage runs through ordered layers — requirements, then milestones, then outcomes → LayeredGraph. The layered graph keeps the order and draws what covers what as lines and words.
A single level against a target → Meter. A meter is one figure on a track; a matrix is many crossings.
A set of verdicts on one row that do not agree → Tally. A tally sums the disagreement in one bar with the counts as words.

Confused with Table, LayeredGraph, Tally, BarChartReact MatrixClasses .matrix

See it on the demo page

`Meter`

Show a level that is simply true, against its scale and target.

Use when

Usage against a quota, capacity used, coverage as a percentage, a score out of a maximum.
A level that should reach a target: threshold draws the tick and says the target in words; tone="auto" reads success or warning off it.

Not when

A task advancing toward done → Progress. role="progressbar" means work under way; a meter means a level, and swapping them misreports what is happening.
Several verdicts on one thing that do not agree → Tally. A tally shows the split with the counts as words; one tone would hide the disagreement.
The number alone carries it, with no scale → Stat. A stat is a figure and a label; a track with no meaningful maximum is decoration.
Comparing the level across many categories → BarChart. Bars on a shared zero compare; a stack of meters does not.

Confused with Progress, Tally, Stat, BarChartReact MeterClasses .meter

See it on the demo page

`Stat`

Show a headline figure with its label and what changed.

Use when

A few KPIs above the content they summarise — put them in a StatRow so the rules between them say they belong together.
A change since last period with StatDelta: direction says which way, good says whether that is good news, and the text says it too.
A figure built from some sources but not all says so in StatNote — and where the count failed, show no figure.

Not when

The figure is a level against a scale or a target → Meter. A meter draws the level on a track and says the target in words; a stat is just the number.
The shape over time matters more than the latest value → LineChart. A trend needs a line with axes; put a Sparkline beside a stat when direction is enough.
Many categories compared by size → BarChart. A row of more than four or five stats is a chart that lost its axis.
Label and value pairs that describe one thing, not measure it → DescriptionList. Attributes are terms and values in body type; a stat is a figure set large.
Totals that add up to a price → Summary. A summary is term and value rows with one emphasised total.

Confused with Meter, Sparkline, DescriptionList, Summary, PageHeadReact Stat StatRow StatLabel StatValue StatNote StatDeltaClasses .stat .stat-row

See it on the demo page

`Summary`

Add lines up to a total the eye lands on.

Use when

An order or a quote: subtotal, delivery, tax, then one total row — one emphasised total per summary.
A note under the figures (SummaryNote) for what the total does or does not include.

Not when

The pairs are properties of a record and nothing adds up → DescriptionList. A description list is plain names and values with no total.
The figures are headline measures, not a sum → Stat. A stat row is figures that read as one sentence; a summary is a sum.
Many line items are compared or sorted → Table. A table compares rows down columns; a summary is a short stack ending in a total.

Confused with DescriptionList, Stat, TableReact Summary SummaryRow SummaryNoteClasses .summary

See it on the template

`Table`

Show records whose values are compared down a column.

Use when

Rows of the same kind with values worth comparing or sorting — status, owner, date, figure.
Sort through Th and useTableSort, so the caret and aria-sort read one value; put filters and a "3 of 240" count in TableToolbar.
Always inside TableWrap, so a wide table scrolls in its own box and never widens the page.

Not when

People type values into the cells → GridTable. A grid has a spreadsheet's keyboard, owned columns and type-ahead per column; a table is read.
The question is which row covers which column — presence and absence on a grid → Matrix. A matrix is one Tab stop with arrow keys, pinned headings, and a mark in every tinted cell.
Each row is read on its own and most columns would be empty → Item. A list of records is a name, a line of provenance and a mark or two; empty columns are noise.
A list of files → DocList. The library rows carry type badges, size and a preview pane.
A handful of label and value pairs about one thing → DescriptionList. One record's attributes are terms and values, not rows.

Confused with GridTable, Matrix, Item, TablePager, DocListReact TableWrap Table TableToolbar Th Td TableEmpty TableEmptyTitleHooks useTableSortClasses .table

See it on the demo page

`TablePager`

Page through a long table and say which rows are on show.

Use when

Under a table too long for one screen: "Showing 26–50 of 61" and the page numbers.
Rows already in memory: usePagedTable sorts the whole set, then pages it, and feeds the pager.

Not when

The table fits on one page → Table. The pager renders nothing then — a "page 1 of 1" control does nothing.
Paging something that is not a table — search results, a gallery → Pagination. Pagination is the bare page list; the table pager adds the range and is wired to usePagedTable.
Stepping one item at a time through a set, inside a pane → PagerChip. The chip says "4 of 19" with previous and next; it is not a page list.

Confused with Pagination, PagerChip, TableReact TablePagerHooks usePagedTable pageRangeClasses .table-pager

See it on the demo page

`Tally`

Show what a set of statements adds up to when they do not agree.

Use when

Five sources say gap and two say covered: one bar split by part, with the counts underneath as words.
On a row where the disagreement is the thing worth opening.

Not when

One value with one tone → Meter. A meter is a single level; a tally is a split.
Nobody has said anything yet → State. A tally with every part at zero renders nothing; say the absence in your own words.
Parts of a whole across categories, compared between rows → BarChart. A stacked bar chart has a shared axis and a legend for many rows.
One settled status → Tag. A single verdict is a status word.

Confused with Meter, BarChart, Matrix, TagReact TallyClasses .tally

No demo page yet.

`Timeline`

Show events in the order they happened.

Use when

A chronology of events with nobody in them — submitted, reviewed, released — each with a time, a title and an optional body.
Marking the live entry: current highlights its marker.

Not when

The history is people doing things, several in a row each → Feed. A feed groups each person's run of actions so the boundaries between people are seen, not read.
People write notes about the thing and reply → Comment. A comment is an authored note with a composer; a timeline entry is an event.
The steps are a process the person is part-way through → Stepper. A stepper shows position in a sequence still to finish; a timeline records what already happened.

Confused with Feed, Comment, Stepper, TranscriptReact Timeline TimelineItemClasses .timeline

See it on the demo page

Other guides: Screens · Overlays · Status and feedback · Navigation · Input · Reading · Agents and live work

Generated from the when.ts beside each component — the same data the Claude Code plugin reads.