An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file CheckboxListItem.tsx
* @input Uses React, CheckboxInput, ListItem, CheckboxListContext,
* CheckboxRowPressContext, the touch presentation and the row press paint
* @output Exports CheckboxListItem component, CheckboxListItemProps
* @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
* - /packages/core/src/CheckboxList/CheckboxList.doc.mjs
* - /packages/core/src/CheckboxList/CheckboxList.test.tsx
* - /packages/core/src/CheckboxList/index.ts
* - /apps/storybook/stories/CheckboxList.stories.tsx
* - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
*/
import {use, useCallback, useId, useRef, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
import type {CheckboxInputProps} from '../CheckboxInput/CheckboxInput';
import type {InputStatus} from '../Field/types';
import {CheckboxRowPressContext} from '../CheckboxInput/CheckboxRowPressContext';
import {rowPressPaintStyles} from '../privateAttributes/press.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {useTouchPresentation} from '../utils/touchPresentation';
import {ListItem} from '../List/ListItem';
import {ListContext} from '../List/ListContext';
import {CheckboxListContext} from './CheckboxListContext';
import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
import {joinAriaIDs} from '../utils/inputAria';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {themeDataAttributes} from '../utils/themeProps';
import type {ItemAlign} from '../Item';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/CheckboxList/CheckboxListItem.generated';
registerEnglishFallback(english);
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
selected: {
backgroundColor: colorVars['--color-accent-muted'],
},
});
// =============================================================================
// Types
// =============================================================================
export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
/**
* Vertical alignment of the start and end content against the label,
* forwarded to Item. Use `first-line` to keep the checkbox level with the
* first line of a wrapped label.
* @default 'center'
*/
align?: ItemAlign;
/**
* Primary text label for the item.
*
* Accepts a plain string (single-line truncation applied automatically)
* or a ReactNode for rich content (no truncation constraints —
* child components control their own text behavior). Links and buttons in
* the label keep their own behavior; only non-interactive row clicks
* delegate to the checkbox.
*
* A string names the checkbox directly. A ReactNode names it from its
* visible text through `aria-labelledby`; if that text is absent, pass
* `aria-label`. When visible text is present, an override must retain every
* visible word so speech-input users can say what they see.
*/
label: ReactNode;
/**
* Plain-text accessible name for the checkbox, replacing the one derived
* from `label`.
*
* A string `label` names the checkbox directly, and a rich (ReactNode)
* `label` names it from its visible text through `aria-labelledby`. Pass
* `aria-label` when that text is absent. When visible text is present, the
* override must retain every visible word so speech-input users can say what
* they see. It replaces the derived name and applies to the checkbox control,
* not the row.
*
* @example
* ```
* <CheckboxListItem
* label={<span>Pro plan <Badge label="Recommended" /></span>}
* aria-label="Pro plan Recommended option"
* value="pro"
* />
* ```
*/
'aria-label'?: string;
/**
* Identity key for collection mode. Required when the parent CheckboxList
* has a `value` array: the item throws without it there. An item inside
* List, or inside a CheckboxList without `value`, may omit it.
*/
value?: string;
/**
* Secondary content below the label. Accepts a plain string or a ReactNode.
* Exposed as the checkbox's accessible description through
* `aria-describedby`, so assistive technology can tell it is the explanation
* for this choice rather than unrelated row text.
*/
description?: ReactNode;
/**
* Content rendered after the label area.
*/
endContent?: ReactNode;
/**
* Whether this individual item is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Whether this item is in a loading state. Renders a spinner inside the
* checkbox and blocks interaction on this item only.
*
* In collection mode, this is also driven automatically: when the parent
* `CheckboxList` has a `changeAction`, the toggled item shows its
* spinner while that promise is pending.
* @default false
*/
isLoading?: boolean;
/**
* Direct checked state for standalone mode: an item inside List, or inside
* a CheckboxList without `value` (for example, a select-all item). Ignored
* when the parent CheckboxList has a `value` array, which then owns the
* checked state.
*/
isChecked?: boolean | 'indeterminate';
/**
* Direct check handler for standalone mode: an item inside List, or inside a
* CheckboxList without `value`. Ignored when the parent CheckboxList has a
* `value` array; that list's `onChange` receives the change instead.
*/
onCheck?: (checked: boolean) => void;
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLLIElement>;
}
// =============================================================================
// Component
// =============================================================================
const ERROR_STATUS: InputStatus = {type: 'error'};
/**
* The row's visible description is the checkbox's accessible description. Item
* renders that element and owns its id, and publishes the id through
* ItemDescriptionContext; this reads it from inside the slot Item renders. The
* row cannot wrap the description in an id'd element instead — that turns a
* plain string into a ReactNode and drops the single-line truncation ListItem
* documents — and a public `descriptionId` prop would fail
* `spec:AST-002/DEC-1`, since the caller decides nothing Item cannot derive.
*
* This component owns `aria-describedby`, so the prop is omitted rather than
* accepted and overwritten: a caller passing one would otherwise lose the id
* silently. After the row's description comes the group's disabled reason
* (CheckboxList's disabledMessage), which describes each checkbox (FR9).
*/
function DescribedCheckboxInput(
props: Omit<CheckboxInputProps, 'aria-describedby'>,
) {
const describedBy = use(ItemDescriptionContext);
const listContext = use(CheckboxListContext);
return (
<CheckboxInput
{...props}
aria-describedby={joinAriaIDs(
describedBy ?? undefined,
listContext?.disabledMessageID,
)}
// The status has no message, so CheckboxInput renders nothing. The list
// renders the message.
status={listContext?.isInvalid ? ERROR_STATUS : undefined}
/>
);
}
/**
* A checkbox item for use within CheckboxList (collection mode, when the list
* has a `value` array) or standalone (inside List, or inside a CheckboxList
* without `value`).
*
* In collection mode, checked state is derived from the parent's value array.
* In standalone mode, uses isChecked/onCheck props directly.
*
* Composes ListItem internally — gets density, dividers, hover/press,
* focus, and container alignment for free.
*
* @example
* ```
* <CheckboxListItem label="Email" value="email" />
* <CheckboxListItem
* label="Accept terms"
* isChecked={accepted}
* onCheck={setAccepted}
* />
* ```
*/
export function CheckboxListItem({
label,
'aria-label': ariaLabel,
value,
description,
endContent,
isDisabled: isItemDisabled = false,
isLoading: isItemLoading = false,
isChecked,
onCheck,
ref,
xstyle,
className,
style,
onClick: onClickProp,
align,
...restProps
}: CheckboxListItemProps) {
const t = useComponentTranslator();
const ctx = use(CheckboxListContext);
if (ctx && ctx.value !== undefined && value === undefined) {
throw new Error(
'CheckboxListItem requires a `value` prop when used inside CheckboxList with a value array.',
);
}
// Accessible name for the checkbox. A string `label` (or an explicit
// `aria-label`) becomes the text of CheckboxInput's visually hidden
// `<label>`, which only accepts a string. A rich label instead names the
// checkbox from the visible label element through `aria-labelledby`, as
// RadioListItem does; the hidden label then carries only the generic word,
// which `aria-labelledby` outranks. Strings are left unwrapped on purpose:
// Item single-line-truncates a raw string label but not a node.
const isRichLabel = typeof label !== 'string';
const labelID = useId();
const namesFromVisibleLabel = isRichLabel && ariaLabel == null;
const checkboxLabel =
ariaLabel ??
(isRichLabel ? t('@astryx.checkboxList.item.checkbox') : label);
// Density from list context for checkbox sizing
const listCtx = use(ListContext);
const density = listCtx?.density ?? 'balanced';
const checkboxSize = density === 'compact' ? 'sm' : 'md';
// Disabled: parent-level OR item-level
const effectiveDisabled = (ctx?.isDisabled ?? false) || isItemDisabled;
const effectiveReadOnly = ctx?.isReadOnly ?? false;
// Loading is per-item: explicit item prop OR (collection mode) an item
// whose `changeAction` is currently pending in the parent.
const isBusy =
isItemLoading ||
(value !== undefined && (ctx?.loadingValues?.includes(value) ?? false));
// Resolve checked state:
// 1. Collection mode (inside CheckboxList with value[])
// 2. Standalone mode (isChecked prop)
// 3. Neither → unchecked
let resolvedChecked: boolean | 'indeterminate' = false;
if (ctx && ctx.value !== undefined && value !== undefined) {
resolvedChecked = ctx.value.includes(value);
} else if (isChecked !== undefined) {
resolvedChecked = isChecked;
}
// Whether this item is interactive (has a toggle handler)
const isInteractive = !effectiveReadOnly && (ctx != null || onCheck != null);
// The checkbox is the row's single keyboard control and action. The row is
// an enlarged click/tap target that delegates surface clicks to it via
// ListItem's `interactiveRef` (useClickableContainer), so each option is
// exactly one tab stop. Delegate whenever the row should respond to clicks:
// a toggleable item, or one carrying a consumer `onClick`.
const checkboxRef = useRef<HTMLInputElement | null>(null);
const hasRowInteraction = isInteractive || onClickProp != null;
// A required group decides which box carries native `required` from the
// state of every box. A change to this box's state registers it again.
const requiredGroup = ctx?.requiredGroup;
const isBoxChecked = resolvedChecked === true;
const isBoxEnabled = !effectiveDisabled && !effectiveReadOnly;
const registerWithRequiredGroup = useCallback(
(input: HTMLInputElement | null) =>
input != null && requiredGroup != null
? requiredGroup.register(input, {
isChecked: isBoxChecked,
isEnabled: isBoxEnabled,
})
: undefined,
[requiredGroup, isBoxChecked, isBoxEnabled],
);
const checkboxInputRef = useMergedRefs(
checkboxRef,
registerWithRequiredGroup,
);
// Under a finger, a delegating row is the option's only press surface. A
// touch anywhere on it presses the row. A fine pointer keeps the box's own
// press.
const {isTouch} = useTouchPresentation();
const rowOwnsPress = isTouch && hasRowInteraction && !effectiveDisabled;
// A read-only checkbox carries aria-readonly, which the row's clickable
// container treats as a non-interactive target, so a click on it would be
// delegated straight back to the checkbox without end. Stop that click at
// the checkbox; the consumer onClick still fires once per click.
const handleCheckboxClick: typeof onClickProp =
effectiveReadOnly && onClickProp != null
? event => {
onClickProp(event);
event.stopPropagation();
}
: onClickProp;
const handleToggle = () => {
if (effectiveDisabled || effectiveReadOnly || isBusy) {
return;
}
if (ctx && ctx.value !== undefined && value !== undefined) {
// Collection mode — pass the toggled value up so the list can show a
// spinner on this item while a changeAction is pending.
const currentlyChecked = ctx.value.includes(value);
if (currentlyChecked) {
ctx.onChange?.(
ctx.value.filter(v => v !== value),
value,
);
} else {
ctx.onChange?.([...ctx.value, value], value);
}
} else {
// Standalone mode
const shouldCheck = resolvedChecked === true ? false : true;
onCheck?.(shouldCheck);
}
};
// The state follows the fill, so a theme can restyle the text on it.
const isCheckedRow =
resolvedChecked === true && !effectiveDisabled && !effectiveReadOnly;
return (
<ListItem
{...restProps}
{...themeDataAttributes({selected: isCheckedRow ? 'selected' : null})}
ref={ref}
label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label}
description={description}
endContent={endContent}
align={align}
isDisabled={effectiveDisabled}
// Delegate row clicks to the checkbox instead of wiring onClick (which
// would add an invisible row button = a second tab stop). The checkbox
// stays the option's sole focusable control (WCAG 4.1.2 / APG checkbox
// pattern). A consumer onClick rides on the checkbox itself (below), so
// it still fires for both direct and delegated (row-surface) clicks.
interactiveRef={hasRowInteraction ? checkboxRef : undefined}
aria-busy={isBusy || undefined}
xstyle={
[
// The row's own press paint, which the layer over its box reads.
rowOwnsPress && rowPressPaintStyles.checkboxRow,
// Item's row layer drops the strength's release, and the box paints
// at that strength. So the row brings the release back, and the box
// fades with the row.
rowOwnsPress && interactionOverlayStyles.pressedAlpha,
isCheckedRow && styles.selected,
xstyle,
] as StyleXStyles
}
className={className}
style={style}
startContent={
// Only the row's own checkbox: a checkbox placed in the row's content
// keeps its own press.
<CheckboxRowPressContext value={rowOwnsPress}>
<DescribedCheckboxInput
ref={checkboxInputRef}
label={checkboxLabel}
aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
isLabelHidden
value={resolvedChecked}
onChange={() => handleToggle()}
onClick={handleCheckboxClick}
isDisabled={effectiveDisabled}
isReadOnly={effectiveReadOnly}
isLoading={isBusy}
size={checkboxSize}
/>
</CheckboxRowPressContext>
}
/>
);
}
CheckboxListItem.displayName = 'CheckboxListItem';