CheckboxList

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Checkbox List

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.

Usage guidance

• Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.
• Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.
• Write a group label that says what the choices represent: "Export formats" tells users more than "Options".
• Avoid: Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.
• Avoid: Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.
• Avoid: Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-checkbox-list"
    }
  ]
}

CheckboxListItem

Anatomy

• Group: Container for the labeled checkbox group.
• Group label: Text identifying what the checkbox options represent.
• Description: Helper text below the group label.
• Options list: List containing the available checkbox options.
• Option row: Selectable row containing one option.
• Checkbox: Selection indicator for an option.
• Option label: Primary content identifying an option.
• Option description: Secondary text below an option label.
• End content: Caller-provided content at the end of an option row.
• Spinner: Loading indicator shown inside the pending checkbox.
• Status message: Error, warning, or success message below the group.

Checkbox List Item

Individual checkbox item with label, description, and end content slot. Works in collection mode (inside a CheckboxList with a value array) or standalone mode (inside List, or inside a CheckboxList without value, such as a select-all item).

Rich label with an overriding aria-label

<CheckboxListItem
  label={<span>Pro plan <Badge label="Recommended" /></span>}
  aria-label="Pro plan Recommended option"
  value="pro"
/>

Examples

• Checkbox List Item: Checkbox list items with labels, descriptions, and different states including disabled.
• Checkbox List:
• CheckboxListItem — Basic: Checkbox items with labels and descriptions inside a controlled CheckboxList. Use for multi-select option groups like notification preferences.
• CheckboxList — Select All With Indeterminate: 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.
• CheckboxList — With End Content: 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.