CheckboxCard

Patterns

Plan Selection Tile

When to use: Present plan features or package options where the whole card should be clickable.

Composition notes: Keep title and description in CheckboxCardContent and render the control on the opposite edge.

Trade-offs: The pattern is expressive, but consumes more space than a normal checkbox row.

import {
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxIndicator,
  Fieldset,
  FieldsetLegend,

Settings Tile With Native Form Participation

When to use: The app wants a rich tile UI, but still submits through a native form.

Composition notes: Give each CheckboxCardControlInput a shared name and its own value, then read the selection with FormData.getAll.

Trade-offs: Form integration becomes easier, but layout and semantics still need to keep the full card readable.

import { FormEvent, useState } from 'react';
import {
  Button,
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxIndicator,

Comparison

Quick Decision Rule

Choose CheckboxCard when each checkbox option needs a card-sized labeled surface. Choose Checkbox, Radio, or SegmentedControl when the UI can stay compact.

CheckboxCard vs Checkbox

Use CheckboxCard when the option includes a title, description, or richer tile layout.

Use Checkbox when a compact inline label is enough.

CheckboxCard vs Radio

Use CheckboxCard for independent multi-select options.

Use Radio when the group is mutually exclusive.

CheckboxCard vs Switch

Use CheckboxCard when:

• multiple rich options can be selected independently

Use Switch when:

• one immediate binary setting should toggle on or off

CheckboxCard vs SegmentedControl

Use CheckboxCard when content is descriptive and card-like.

Use SegmentedControl when options should stay short, dense, and always visible.

Choose This Component When

• the whole card should be the selection target
• the option needs title and description content
• multi-select semantics still apply
• richer option content matters more than density

Do Not Choose This Component When

• the group is single-select
• the option content is short enough for a normal checkbox
• the UI needs high-density controls instead of tiles

Troubleshooting

Only The Tiny Control Feels Clickable

Symptom

Users click the card body, but the option does not feel like a full-card control.

Likely Cause

Custom composition or styling broke the labeled card surface and left only the small control looking interactive.

How To Verify

• test pointer interaction on the entire card
• inspect whether the root still renders as the labeled click target

Fix

Keep the root card-label composition intact and avoid pointer-event overrides that isolate the control.

The Card Does Not Participate In Native Form Submission

Symptom

The checked state changes visually, but the expected value is missing from FormData.

Likely Cause

CheckboxCardControlInput is missing.

How To Verify

• submit the form
• inspect FormData

Fix

Render CheckboxCardControlInput inside the control region.

Indeterminate State Never Appears

Symptom

The UI should show a mixed state, but the card only looks checked or unchecked.

Likely Cause

indeterminate was not passed, or the custom control rendering omitted the indeterminate icon path.

How To Verify

• inspect the root props
• compare the custom control with the shipped stories

Fix

Pass indeterminate and keep CheckboxCardControlIndeterminateIcon in the control composition when that state matters.