You're in the Library

Checklist

The steps or conditions something needs, one row each: a status icon, a title, one line of detail and, when there is one, the action on the same row. Like the merge box of a pull request.
Stable
Edit

Preview appears after the next Storybook update.

Checklist example
<Checklist />
Rendered with the real componentFrom the code
Light
Dark

When to use

Use it for

  • What a change needs before it ships: design rules, developer tests, design approval.
  • A short setup the reader goes through once, where each step has a clear done state.
  • Put the action for a row on that row (an Approve button next to Design approval), as a Button with size sm and variant secondary. On narrow screens it takes the full width under the row.
  • Use footer for what the rows add up to: why it waits, and the one way to unblock it.
  • Plain-script pages that build rows as HTML strings use checklistHtml() and checklistRowHtml() from @bridge-ds/react/dom: the same markup, status icons and screen reader words, without React.

Not for

  • Something the reader ticks off: use Checkbox. A Checklist row shows a status the system knows, it is not a control.
  • A single message about the page: use Alert.
  • A long log of events in time: use a list or a table with dates.
  • Steps the reader moves through one screen at a time: use a stepper or Tabs.

Do and don't

Every example is rendered with the real component, so it always matches what ships.

  • Design approvalWaiting: Waiting on a design owner.
Do

Say who or what each row waits on

The detail turns a status into a next step: "Waiting on a design owner" tells the reader whom to ask.

  • Design rulesDone: All 14 rules pass.
  • Developer testsFailed: 2 of 212 tests fail: Button focus ring, Select keyboard.
Do

Name what failed, with numbers

"2 of 212 tests fail" says how bad it is and where to look. "Tests failed" does not.

  • Developer testsFailed:
  • Design approvalWaiting:
Don't

A title without a detail

An icon and a title alone leave the reader guessing what to do. Every row that is not done says why in one line.

  • Design approvalNeeds attention: Waiting on a design owner.
Don't

Warning for something that simply waits

Waiting is normal: use the empty ring. Keep warning for a row that needs attention, such as an approval given before the last change.

Accessibility

  • A list (ul) named by label: "What it needs to ship, list, 3 items".
  • Each row says its status in words before the detail (Done, Failed, Waiting, Needs attention), in visually hidden text. The icon is decorative, so color and shape are never the only signal. Override the words per row with statusLabel.
  • A row's action is a real Button on the row, reached with Tab in reading order, after the row it acts on.
  • Feedback icon colors are checked against their tinted backgrounds in both themes.
  • Static markup: no hydration needed. Plain scripts render the same markup with checklistHtml() and checklistRowHtml() from @bridge-ds/react/dom.

Content guidelines

  • Label: what the rows add up to, sentence case: "What it needs to ship".
  • Title: the condition as a noun, a few words: "Design approval", "Developer tests".
  • Detail: one line, the state in plain words, with who or what it waits on and numbers when there are some.
  • Action: a verb for the next step on that row: "Approve", "View tests", "Ask again".

From the code Generated from the component, not editable here.

Anatomy and tokens

Read from packages/react/src/components/Checklist/Checklist.module.css at build time. Every value is a token: open one to see its alias chain in both themes.

27 tokens13 semantic or component, change with theme and brand1 density, change with comfortable or compact13 from the shared scales

Motion and interaction

Checklist does not animate: its states change at once.

From the code Generated from the component, not editable here.

Props

Parsed from the TypeScript types in packages/react/src/components/Checklist/Checklist.tsx, so this table cannot drift from the code. It also accepts every native <HTMLUListElement> attribute.

PropTypeDefaultDescription
labelstringnoneAccessible name of the list: what the rows add up to, "What it needs to ship".
footerReactNodenoneText and actions under the rows, in the same plate: why something waits, a way to unblock it.
childrenReactNodenoneChecklistRow elements.

Playground

Change the props and see the real Checklist update. Controls are generated from the TypeScript props; nothing here changes the system.

Code for these props
<Checklist label="What it needs to ship" />

Workbench

For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Checklist in Storybook).

Embed Storybook stories here (5)

Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.

Default

Blocked

ReadyToShip

NarrowWithAction

AllStates

From the code Generated from the component, not editable here.

Changelog

  • Fix

    Checklist: rows ignore a page's list spacing, so a highlighted row fills its whole band up to the dividers

    v1.0.0, Nov 11, 2026

  • Fix

    Check the build: the exploration page shows a short list of where the build differs (one line each, the two versions under a line on hover or focus, the header primary following progress), the handover notes become a checklist whose ticks are saved, the check page walks the differences with a stepper and ends on a recap with one Send

    v1.0.0, Nov 11, 2026

All release notes

Updated Nov 11, 2026
View source

Generated from 4 files