An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file CheckboxInput.tsx
* @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip,
* CheckboxRowPressContext (a row around the checkbox that owns its press)
* @output Exports CheckboxInput component, CheckboxInputProps
* @position Core implementation; consumed by index.ts, tested by CheckboxInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/CheckboxInput/CheckboxInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/CheckboxInput/CheckboxInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/CheckboxInput/index.ts (exports if types change)
* - /apps/storybook/stories/CheckboxInput.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/CheckboxInput/ (showcase blocks)
*/
import {
use,
useId,
useCallback,
useOptimistic,
useRef,
useTransition,
type ChangeEvent,
type FocusEvent,
type MouseEvent as ReactMouseEvent,
type PointerEvent as ReactPointerEvent,
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
radiusVars,
typographyVars,
typeScaleVars,
fontWeightVars,
} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {FieldLabel} from '../Field/FieldLabel';
import {FieldStatus} from '../FieldStatus/FieldStatus';
import type {IconType} from '../Icon';
import type {InputStatus} from '../Field/types';
import {Spinner} from '../Spinner/Spinner';
import {useTooltip} from '../Tooltip/useTooltip';
import {mergeProps} from '../utils/mergeProps';
import {rtlStyles} from '../utils/rtlStyles';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {indicatorScope} from '../Indicator/indicator.markers.stylex';
import {indicatorPressScope} from '../internal/indicatorPress.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {useIndicator} from '../Indicator/useIndicator';
import {themeProps} from '../utils/themeProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useTouchHitArea} from '../utils/touchHitArea';
import {pressBoxProps} from '../privateAttributes/pressBox.stylex';
import {registerBoxHold} from '../utils/boxHold';
import {touchHitAreaStyles} from '../internal/touchHitArea.stylex';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/CheckboxInput/CheckboxInput.generated';
import {CheckboxRowPressContext} from './CheckboxRowPressContext';
registerEnglishFallback(english);
// Registered here, not in the press controller, so a page with no box carries
// none of its code.
registerBoxHold();
/** Written by the touch press controller while the row is pressed. */
const PRESSED_ON = '[data-astryx-press="on"]';
/** Written by the touch press controller for the press's release. */
const PRESSED_FADING = '[data-astryx-press="fading"]';
// The touch press's paint, declared by the shared overlay styles on the
// element the controller writes to (`pressedAlpha`) at the press's strength,
// 1 while on and 1 → 0 over the release, and inherited resolved by the layer
// that paints it. See interactionOverlay.stylex.ts.
const pressedOverlayImage = 'var(--_press-paint-image)';
const styles = stylex.create({
container: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
},
containerLabelHidden: {
gap: 0,
},
// Under a coarse pointer the row contains its hit band.
hitAreaHost: {
position: {default: null, '@media (pointer: coarse)': 'relative'},
},
// An indicator in another package may not name this row's private press
// attribute. So the row hands its touch press image down to an indicator
// that paints its own press, but only in its own press states. A pressed
// outer row hands down nothing, as for the built-in box. The
// property has no default: a layered stylesheet ranks a default above the
// arms. Only this row declares it. A menu item paints its own press, so a
// mapped indicator there paints none.
indicatorPressImage: {
'--_indicator-press-image': {
default: null,
[PRESSED_ON]: 'var(--_press-paint-image)',
[PRESSED_FADING]: 'var(--_press-paint-image)',
},
},
// Under a row that owns the press (CheckboxRowPressContext), this row is
// never pressed. So it hands down that row's press paint, which the
// built-in box reads too.
indicatorRowPressImage: {
'--_indicator-press-image': 'var(--_checkbox-row-press-paint, none)',
},
checkboxWrapper: {
position: 'relative',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
isolation: 'isolate',
},
// The owner paints this layer over the resolved indicator, so a plain theme
// replacement keeps the pressed feedback. An indicator with
// `indicatorPressScope` paints its own press from what the row hands down,
// so this layer stays off over it. A mouse keeps `:active` (see
// interactionOverlay.stylex.ts). Under a coarse pointer that arm is dropped.
// The touch press controller then writes the press attribute on the row.
// This layer reads it off the scope marker, as the hover tint does. Under a
// row that owns the press (CheckboxRowPressContext), the row's own checkbox
// paints that row's press paint instead (indicatorRowPressOverlay).
indicatorPressOverlay: {
'::after': {
// `when.descendant` takes a pseudo-class; `:is(*)` matches any marked
// indicator.
content: {
default: '""',
[stylex.when.descendant(':is(*)', indicatorPressScope)]: 'none',
},
position: 'absolute',
inset: 0,
borderRadius: radiusVars['--radius-inner'],
pointerEvents: 'none',
backgroundColor: {
default: 'transparent',
[stylex.when.ancestor(':active', indicatorScope)]: {
default: colorVars['--color-overlay-pressed'],
'@media (pointer: coarse)': 'transparent',
},
},
// The touch press, as an image layer over the colour: an image change is
// discrete, so no transition can delay the onset, and the strength the
// row's `pressedAlpha` arms own (1 while on, 1 → 0 over the release) is
// what moves. Coarse pointers only, like the drop above.
backgroundImage: {
default: null,
[stylex.when.ancestor(PRESSED_ON, indicatorScope)]: {
default: null,
'@media (pointer: coarse)': pressedOverlayImage,
},
[stylex.when.ancestor(PRESSED_FADING, indicatorScope)]: {
default: null,
'@media (pointer: coarse)': pressedOverlayImage,
},
},
},
},
// The row's own checkbox when its row owns the press
// (CheckboxRowPressContext). It paints only the paint that row declares
// (`--_checkbox-row-press-paint`). No outer row, card or fine pointer
// reaches it.
indicatorRowPressOverlay: {
'::after': {
backgroundImage: 'var(--_checkbox-row-press-paint, none)',
},
},
// Holds only the indicator, so the focus ring has one unambiguous target.
// `display: contents` adds no box of its own — the indicator keeps whatever
// layout relationship it already had with the wrapper.
indicatorSlot: {
display: 'contents',
},
input: {
position: 'absolute',
top: '50%',
margin: 0,
padding: 0,
opacity: 0,
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
zIndex: 1,
},
inputCoarse: {
'@media (pointer: coarse)': {
minInlineSize: 24,
minBlockSize: 24,
},
},
inputDisabled: {
cursor: 'default',
},
labelWrapper: {
display: 'flex',
flexDirection: 'column',
},
description: {
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontWeight: fontWeightVars['--font-weight-normal'],
color: colorVars['--color-text-secondary'],
},
});
const wrapperSizeStyles = stylex.create({
sm: {
width: 20,
height: 20,
},
md: {
width: 24,
height: 24,
},
});
export type CheckboxInputSize = keyof typeof wrapperSizeStyles;
export interface CheckboxInputProps extends Omit<BaseProps, 'onChange'> {
/** Ref forwarded to the underlying `<input>` element */
ref?: React.Ref<HTMLInputElement>;
/**
* Label text for the checkbox (always rendered for accessibility).
*/
label: string;
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
*/
isLabelHidden?: boolean;
/**
* Description text displayed below the label.
*/
description?: string;
/**
* Callback fired when the checkbox state changes.
*/
onChange?: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void;
/**
* Async action on change. Fires after onChange if not prevented.
*/
changeAction?: (
checked: boolean,
e: ChangeEvent<HTMLInputElement>,
) => void | Promise<void>;
/**
* Whether the checkbox is in a loading state.
* @default false
*/
isLoading?: boolean;
/**
* Whether the checkbox is checked, unchecked, or indeterminate.
*/
value: boolean | 'indeterminate';
/**
* Whether the checkbox is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* The HTML name attribute for the underlying checkbox input.
* Useful for form submissions.
*/
htmlName?: string;
/**
* Explains why the checkbox is disabled. When set together with
* `isDisabled`, the checkbox shows a tooltip with this text on hover and
* keyboard focus, and the control stays focusable (via `aria-disabled`) so
* the reason is discoverable by keyboard and assistive technology.
* Activation stays blocked.
*
* Use this instead of wrapping a disabled checkbox in `Tooltip` — disabled
* controls don't emit the pointer events an external tooltip needs.
*
* @example
* ```
* <CheckboxInput
* label="Accept terms"
* value={accepted}
* isDisabled
* disabledMessage="Terms are managed by your administrator"
* />
* ```
*/
disabledMessage?: string;
/**
* Whether the checkbox is read-only.
* Displays the current state at full opacity but prevents interaction.
* Unlike `isDisabled`, read-only checkboxes are not visually dimmed.
* @default false
*/
isReadOnly?: boolean;
/**
* Whether the field is optional. Mutually exclusive with isRequired.
* @default false
*/
isOptional?: boolean;
/**
* Whether the checkbox is required. Mutually exclusive with isOptional.
* @default false
*/
isRequired?: boolean;
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
* stay aligned, unlike setting width via `xstyle`/`className`/`style`.
*/
width?: SizeValue;
/**
* The size of the checkbox.
* - 'sm': Compact size (28px row height)
* - 'md': Default size (36px row height)
* @default 'md'
*/
size?: CheckboxInputSize;
/**
* Callback fired when the checkbox receives focus.
*/
onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
/**
* Callback fired when the checkbox loses focus.
*/
onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
/**
* Icon to display before the label text.
*/
labelIcon?: ReactNode | IconType;
/**
* Status indicator for the checkbox.
* When set with a message, displays a colored message box below the checkbox.
*/
status?: InputStatus;
}
// Dynamic field width (number -> px, string used as-is).
const dynamicWidthStyles = stylex.create({
width: (width: SizeValue | null) => ({width}),
});
/**
* A checkbox input component for toggling boolean values.
*
* @example
* ```
* <CheckboxInput
* label="Accept terms"
* value={accepted}
* onChange={setAccepted}
* />
* <CheckboxInput
* label="Subscribe"
* description="Receive weekly updates"
* value={subscribed}
* onChange={setSubscribed}
* />
* ```
*/
export function CheckboxInput({
id: idProp,
label,
isLabelHidden = false,
description,
onChange,
changeAction,
isLoading = false,
value,
isDisabled = false,
htmlName,
disabledMessage,
isReadOnly = false,
isOptional = false,
isRequired = false,
size = 'md',
onFocus,
onBlur,
labelIcon,
status,
width,
xstyle,
className,
style,
ref,
'aria-describedby': ariaDescribedByProp,
...rest
}: CheckboxInputProps) {
// The row is the pressable: the overlay's pressed arm reads the row's
// scope marker, the way the indicator's hover tint does.
const pressable = usePressFeedback();
// A row around the checkbox that answers a press anywhere on it (a
// CheckboxListItem) owns the touch press instead. The checkbox then carries
// no press marker of its own. So the controller's innermost-wins rule finds
// the row for a finger on the label, the description or the box. The
// overlay below paints that row's press.
const isRowPressSurface = use(CheckboxRowPressContext);
const ownsPress = !isDisabled && !isRowPressSurface;
const generatedId = useId();
const id = idProp || generatedId;
const descriptionID = useId();
const statusMessageID = useId();
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isBusy = isLoading || optimisticValue !== value;
// A disabled checkbox stays focusable via aria-disabled instead of the
// native disabled attribute (spec:AST-085 FR1). Value mutation is blocked by
// the click and onChange guards on the input.
const showsDisabledMessage = isDisabled && !!disabledMessage;
const disabledMessageTooltip = useTooltip({
placement: 'above',
// The container row is not naturally focusable; focusin bubbles up from the
// native checkbox, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
// The checkbox visual is an indicator: a theme can restyle it through the
// canonical `checkbox-indicator` target or replace the component outright.
const CheckboxControl = useIndicator('checkbox');
// The ring is drawn on the indicator itself: the native input is
// `opacity: 0`, and only the indicator's own element can shape the outline
// to match it. See useIndicatorFocusRing.
const indicatorRef = useRef<HTMLSpanElement>(null);
const t = useComponentTranslator();
// The busy Spinner sits in the decorative, aria-hidden indicator, so this
// control announces its busy start itself (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), indicatorRef);
const {focusProps} = useIndicatorFocusRing(indicatorRef);
// Under a coarse pointer a labelled checkbox's row grows toward 44 px
// through an invisible band, and nothing changes size. A label-hidden
// checkbox is a marker in another component's row, which keeps its target.
const hasHitArea = !isLabelHidden && !isDisabled && !isReadOnly;
const inputRef = useRef<HTMLInputElement>(null);
// The band's insets stay live while the row takes taps, and clear when it
// stops.
const watchRowHitArea = useTouchHitArea(hasHitArea);
// The disabled-message tooltip listens for hover and focus on the whole
// row, a larger trigger. It anchors on the checkbox itself (below), so it
// shows next to the control. Its handlers check isEnabled, so the row
// always attaches them.
const rowRef = useMergedRefs(
disabledMessageTooltip.interactionRef,
watchRowHitArea,
);
// Where a press on the row itself began. A browser can move a tap's click
// onto the row's edge, so the band is judged from the press.
const pressPointRef = useRef<{x: number; y: number} | null>(null);
const handleRowPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
pressPointRef.current =
event.target === event.currentTarget
? {x: event.clientX, y: event.clientY}
: null;
};
// A press that began on the band, outside the row's box, toggles the
// checkbox, as a tap on the box does. A click from code has no press count
// (`detail` is 0), so it never toggles from here.
const handleRowClick = (event: ReactMouseEvent<HTMLDivElement>) => {
const press = pressPointRef.current;
pressPointRef.current = null;
if (
press == null ||
event.detail === 0 ||
event.target !== event.currentTarget
) {
return;
}
const box = event.currentTarget.getBoundingClientRect();
const isOnBand =
press.x < box.left ||
press.x > box.right ||
press.y < box.top ||
press.y > box.bottom;
if (isOnBand) {
inputRef.current?.click();
}
};
const isIndeterminate = optimisticValue === 'indeterminate';
const isChecked = optimisticValue === true;
// Sync the native indeterminate DOM property (can't be set via JSX
// attribute). On a native checkbox this is the authoritative way to expose
// the mixed state — a separate aria-checked="mixed" would be redundant and
// can desync from / override the native state (forms-16), so it is omitted.
const indeterminateRef = useCallback(
(el: HTMLInputElement | null) => {
if (el) {
el.indeterminate = isIndeterminate;
}
},
[isIndeterminate],
);
// Build aria-describedby from description and status message
// Only include descriptionID when the element actually renders.
// FieldLabel renders the description (with descriptionID) even when the
// label is visually hidden — it's sr-only, so keep it linked.
// A consumer's own `aria-describedby` (CheckboxListItem points the control
// at its visible row description) comes first, then the input's own ids —
// the explicit attribute below would otherwise replace it via `...rest`.
const describedByParts: string[] = [];
if (ariaDescribedByProp) {
describedByParts.push(ariaDescribedByProp);
}
if (description) {
describedByParts.push(descriptionID);
}
if (status?.message) {
describedByParts.push(statusMessageID);
}
if (showsDisabledMessage) {
describedByParts.push(disabledMessageTooltip.describedBy);
}
const ariaDescribedBy =
describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
return (
<div
{...mergeProps(
themeProps('checkbox-input', {size}),
stylex.props(width != null && dynamicWidthStyles.width(width), xstyle),
className,
style,
)}>
<div
ref={rowRef}
onPointerDown={hasHitArea ? handleRowPointerDown : undefined}
onClick={hasHitArea ? handleRowClick : undefined}
{...(ownsPress ? pressable : undefined)}
{...stylex.props(
styles.container,
isLabelHidden && styles.containerLabelHidden,
hasHitArea && styles.hitAreaHost,
hasHitArea && touchHitAreaStyles.layer,
// Hover and focus reach the checkbox visual through this ancestor
// marker rather than props, so the whole row drives it.
!isDisabled && indicatorScope,
!isDisabled &&
(isRowPressSurface
? styles.indicatorRowPressImage
: styles.indicatorPressImage),
// The touch press's strength and release live on the row the
// controller writes to; the layer over the checkbox box inherits
// and paints it. Under a row that owns the press, the box inherits
// that row's strength instead.
ownsPress && interactionOverlayStyles.pressedAlpha,
)}>
<div
// iOS answers a long hold on the box with a text selection and no
// click. The press controller holds the row's selection for a press
// on the marked box, and checks it if no click comes.
{...(isDisabled ? undefined : pressBoxProps)}
{...stylex.props(
styles.checkboxWrapper,
wrapperSizeStyles[size],
!isDisabled && styles.indicatorPressOverlay,
!isDisabled && isRowPressSurface && styles.indicatorRowPressOverlay,
)}
{...focusProps}>
<input
// A disabled checkbox stays focusable, so it still receives key and
// pointer events. It runs no caller handler except `onFocus` and
// `onBlur`.
{...withholdCallerHandlers(rest, isDisabled)}
ref={useMergedRefs(
ref,
indeterminateRef,
disabledMessageTooltip.positionRef,
inputRef,
)}
id={id}
type="checkbox"
// Withhold the name while disabled: the input stays focusable (not
// natively disabled), and a disabled control must not submit.
name={isDisabled ? undefined : htmlName}
checked={isChecked}
aria-disabled={isDisabled ? 'true' : undefined}
// Detached from its form while disabled, so it neither submits nor
// blocks submission through `required` (spec:AST-085 FR3).
form={isDisabled ? '' : undefined}
// Native `disabled` suppressed onClick (FR2); preventDefault here
// would desync React's controlled checked state.
onClick={isDisabled ? undefined : rest.onClick}
readOnly={isReadOnly}
required={isRequired}
// A form's required default sets nothing here: an unchecked box is an answer.
aria-required={isRequired ? 'true' : undefined}
onChange={e => {
if (isDisabled || isBusy || isReadOnly) {
// Activation clears the native mixed state; React restores
// only `checked`, so restore `indeterminate` too.
e.target.indeterminate = isIndeterminate;
return;
}
const checked = e.target.checked;
onChange?.(checked, e);
if (changeAction && !e.defaultPrevented) {
startTransition(async () => {
setOptimisticValue(checked);
await changeAction(checked, e);
});
}
}}
onFocus={onFocus}
onBlur={onBlur}
aria-readonly={isReadOnly || undefined}
aria-describedby={ariaDescribedBy}
aria-invalid={status?.type === 'error' ? true : undefined}
aria-busy={isBusy || undefined}
{...stylex.props(
styles.input,
rtlStyles.centerInline('-50%'),
styles.inputCoarse,
wrapperSizeStyles[size],
isDisabled && styles.inputDisabled,
)}
/>
{/*
* A container holding ONLY the indicator, so the focus ring has an
* unambiguous target whatever a theme renders. `display: contents`
* keeps it out of layout entirely.
*/}
<span ref={indicatorRef} {...stylex.props(styles.indicatorSlot)}>
<CheckboxControl
state={
isIndeterminate
? 'indeterminate'
: isChecked
? 'checked'
: 'unchecked'
}
size={size}
isDisabled={isDisabled}>
{isBusy ? <Spinner size="sm" shade="inherit" /> : null}
</CheckboxControl>
</span>
</div>
<div {...stylex.props(styles.labelWrapper)}>
<FieldLabel
// A checkbox's label shares a row with its control, unlike a form
// field's label above its input. Naming the label rather than the
// arrangement means a theme asks for the thing it wants, and the
// component that actually knows what this is says so.
{...themeProps('checkbox-label')}
label={label}
inputID={id}
isLabelHidden={isLabelHidden}
isDisabled={isDisabled}
isOptional={isOptional}
isRequired={isRequired}
labelIcon={labelIcon}
description={description}
descriptionID={descriptionID}
/>
</div>
</div>
{status?.message && (
<FieldStatus
type={status.type}
message={status.message}
id={statusMessageID}
variant="detached"
/>
)}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</div>
);
}
CheckboxInput.displayName = 'CheckboxInput';