CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.
ts
| Guidance | Practices |
|---|---|
| Do | Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling. |
| Do | Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together. |
| Do | Write a group label that says what the choices represent: "Export formats" tells users more than "Options". |
| Don't | Show a CheckboxList when the user can only pick one thing; that is what RadioList is for. |
| Don't | Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets. |
A "select all" toggle at the top of a checkbox list that switches to an indeterminate dash when only some items are checked, useful for bulk actions like exporting documents or assigning permissions where users often want everything at once.
Badges in the trailing slot show contextual info, like a price or status, next to each option without cluttering the label, so users can compare choices at a glance.