Checkbox

• Component overview: Checkbox control supporting checked, unchecked, and indeterminate states.
• Interaction: The current spec covers the unchecked, checked, indeterminate, disabled, and hover main matrix.
• Implementation note: Checkbox retains the base selection semantics; the design layer owns the border, fill, and icon visuals.
• Figma spec

Basic Usage

Result

Loading...

Live Editor

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox aria-label="Option A" />
    <Checkbox defaultChecked aria-label="Option B" />
    <Checkbox checked="indeterminate" aria-label="Option C" />
  </div>,
)

Disabled State

Result

Loading...

Live Editor

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox disabled aria-label="Disabled unchecked" />
    <Checkbox disabled defaultChecked aria-label="Disabled checked" />
    <Checkbox disabled checked="indeterminate" aria-label="Disabled indeterminate" />
  </div>,
)

Hover and Main Matrix

Result

Loading...

Live Editor

render(
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24, alignItems: 'center' }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox aria-label="Unchecked default" />
      <span style={{ fontSize: 12, color: '#999' }}>Unchecked Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox className="border-(--Labels-Primary)" aria-label="Unchecked hover" />
      <span style={{ fontSize: 12, color: '#999' }}>Unchecked Hover</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox defaultChecked aria-label="Checked default" />
      <span style={{ fontSize: 12, color: '#999' }}>Checked Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox checked="indeterminate" aria-label="Indeterminate default" />
      <span style={{ fontSize: 12, color: '#999' }}>Indeterminate Default</span>
    </div>
  </div>,
)

With Label

Pass label to make the entire row (control + text) clickable.

Result

Loading...

Live Editor

render(<Checkbox label="Accept terms of service" />)

Round Shape

shape="round" 对应 Figma Checkmark - Fill 组件，适用于需要圆形选框的场景（如列表选择项）。圆形变体不包含 indeterminate 状态。

Result

Loading...

Live Editor

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox shape="round" aria-label="Round unchecked" />
    <Checkbox shape="round" defaultChecked aria-label="Round checked" />
    <Checkbox shape="round" disabled aria-label="Round disabled unchecked" />
    <Checkbox shape="round" disabled defaultChecked aria-label="Round disabled checked" />
  </div>,
)

Namespace Usage

Result

Loading...

Live Editor

render(
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
    <Controls.Checkbox defaultChecked aria-label="Namespace checkbox" />
    <span style={{ fontSize: 14 }}>Controls.Checkbox</span>
  </div>,
)

Checkbox Props

Prop	Type	Default	Description
checked	boolean | 'indeterminate'	—	Controlled checked state
defaultChecked	boolean	—	Default checked (uncontrolled)
shape	'square' | 'round'	'square'	Shape variant; round maps to Figma Checkmark - Fill
label	string	—	Label text; when set, the entire row is clickable
disabled	boolean	false	Disabled
labelClassName	string	—	Custom style class for the label row
onCheckedChange	(checked: boolean) => void	—	Checked state change callback
aria-label	string	—	Accessibility label
className	string	—	Custom style class