Preview loads on approachPreview loads on approach
Exact source · checkbox-list-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
import {useState} from 'react';
import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
export default function CheckboxListShowcase() {
const [value, setValue] = useState<string[]>(['email']);
return (
<CheckboxList
label="Notification preferences"
description="Choose how you would like to be notified"
value={value}
onChange={setValue}
hasDividers>
<CheckboxListItem
label="Email"
value="email"
description="Weekly digest every Monday"
/>
<CheckboxListItem
label="Push notification"
value="push"
description="Instant alerts on your device"
/>
<CheckboxListItem
label="SMS"
value="sms"
description="Standard messaging rates apply"
/>
</CheckboxList>
);
}
Usage
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.
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".
Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.
Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.
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.
Typed props
Prop
Type and behavior
label
string · required
Label text for the checkbox group (always rendered for accessibility).
Async action on change with optimistic updates. While the promise is pending, the toggled item shows a spinner inside its checkbox and is marked aria-busy.
Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkboxes focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
