Checkbox·component·@astryxdesign/core

Checkbox Input

CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.

Open in Playground @astryxdesign/core/CheckboxInput

Showcases and examples

4 documented examples

Checkbox Input

Interactive checkboxes showing checked, unchecked, and indeterminate states with descriptions.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · checkbox-input-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
import {Stack} from '@astryxdesign/core/Layout';

export default function CheckboxInputShowcase() {
  const [notifications, setNotifications] = useState(true);
  const [marketing, setMarketing] = useState(false);

  return (
    <Stack direction="vertical" gap={2}>
      <CheckboxInput
        label="Checked"
        value={notifications}
        onChange={setNotifications}
      />
      <CheckboxInput
        label="Unchecked"
        value={marketing}
        onChange={setMarketing}
      />
    </Stack>
  );
}

Usage

CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.

Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.
Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.
Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.
Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.
Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.
Wrap a disabled checkbox 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
`ref`	`React.Ref<HTMLInputElement>` Ref forwarded to the underlying <input> element.
`label`	`string` · required Label text for the checkbox (always rendered for accessibility).
`isLabelHidden`	`boolean` · default false Whether to visually hide the label (still accessible to screen readers).
`description`	`string` Description text displayed below the label.
`value`	`boolean \| 'indeterminate'` · required Whether the checkbox is checked, unchecked, or indeterminate.
`onChange`	`(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void` Callback fired when the checkbox state changes.
`changeAction`	`(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void \| Promise<void>` Async action on change. Fires after onChange if not prevented. Shows loading spinner while pending.
`isLoading`	`boolean` · default false Whether the checkbox is in a loading state. Shows spinner and prevents interaction.
`isDisabled`	`boolean` · default false Whether the checkbox is disabled.
`htmlName`	`string` The HTML name attribute for the underlying checkbox input, useful for form submissions (submits "on" when checked).
`disabledMessage`	`string` Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
`isReadOnly`	`boolean` · default false 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.
`isOptional`	`boolean` · default false Whether the field is optional. Mutually exclusive with isRequired.
`isRequired`	`boolean` · default false Whether the checkbox is required. Mutually exclusive with isOptional.
`size`	`'sm' \| 'md'` · default 'md' The size of the checkbox. sm for compact layouts, md for default.
`onFocus`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the checkbox receives focus.
`onBlur`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the checkbox loses focus.
`labelIcon`	`ReactNode \| IconType` Semantic icon name or custom content displayed before the label text. See `astryx docs icons` for valid semantic names.
`status`	`{ type: 'error' \| 'warning' \| 'success', message: string }` Status indicator. Displays a colored message box below the checkbox and sets aria-invalid for errors.
`width`	`SizeValue` Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.

Anatomy

Checkbox · required

The check box itself: unchecked, checked, or indeterminate.

Label · required

Text describing what the checkbox controls. Always present for accessibility.

Description · optional

Helper text below the label with additional context.

Status message · optional

An error, warning, or success message below the checkbox.

Accessibility

Checkbox box

Color contrast · 1.4.11 Non-text Contrast · 3:1

The box edge (unchecked) and fill (checked) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.

States: Rest, Hover, Pointer down, Checked

Theming

Targets

astryx-checkbox-input

Visual props: size

astryx-checkbox-indicator

Visual props: size

States: checked, disabled

astryx-checkbox

Visual props: size

States: checked, disabled

Deprecated; use checkbox-indicator.

astryx-checkbox-label