Checkbox Card

Checkbox cards combine a checkbox with a card layout, allowing users to select options with rich contextual information. Ideal for settings, plan selection, or any multi-select scenario where visual hierarchy matters.

Basic Usage

import { CheckboxCard } from '@/components'

<CheckboxCard
  label="Enable notifications"
  subtext="Receive updates about your account activity"
  checked={checked}
  onCheckedChange={setChecked}
/>

Enable notifications

Receive updates about your account activity

Variants

Checkbox cards support four visual variants to accommodate different content types.

Text variant (default)

Text optionDefault

Simple text-only card

Icon variant

GitLab IntegrationPopular

Connect your GitLab account

Avatar variant

Sofia Martinez

Product Designer

Card Provider variant

Apple Pay

Pay with Apple Pay

Text (Default)

Simple text-only card with label, subtext, and optional badge.

<CheckboxCard
  label="Text option"
  subtext="Simple text-only card"
  badge="Default"
/>

Icon

Card with a circular icon container, great for integrations or feature toggles.

<CheckboxCard
  variant="icon"
  label="GitLab Integration"
  subtext="Connect your GitLab account"
  icon={<GitLabIcon />}
/>

Avatar

Card with an avatar image, perfect for user selection or team members.

<CheckboxCard
  variant="avatar"
  label="Sofia Martinez"
  subtext="Product Designer"
  avatar={<img src="..." alt="Sofia" />}
/>

Card Provider

Card with a payment provider or brand icon.

<CheckboxCard
  variant="cardProvider"
  label="Apple Pay"
  subtext="Pay with Apple Pay"
  cardProvider={<GooglePayIcon />}
/>

States

Checkbox cards support multiple visual states to indicate selection, errors, and disabled states.

Default - Unselected

Unselected option

Click to select

Default - Selected

Selected option

This option is selected

Error

Required field

Please select this option to continue

Disabled - Unselected

Disabled optionBadge

This option is not available

Disabled - Selected

Disabled selectedBadge

This option is locked

Selected

When checked, the card displays a blue border to indicate selection.

<CheckboxCard label="Selected option" checked />

Error

Use the error state for validation errors or required fields.

<CheckboxCard label="Required field" error />

Disabled

Disabled cards cannot be interacted with and display muted styling.

<CheckboxCard label="Disabled option" disabled />
<CheckboxCard label="Disabled selected" disabled checked />

Clickable Behavior

Control whether the entire card or just the checkbox is interactive.

clickableCard=true (default)

Click anywhere

The entire card is clickable

clickableCard=false

Click checkbox only

Only the checkbox is interactive

Entire Card (Default)

By default, clicking anywhere on the card toggles the checkbox.

<CheckboxCard
  label="Click anywhere"
  clickableCard={true}  // default
/>

Checkbox Only

Set clickableCard={false} to make only the checkbox interactive.

<CheckboxCard
  label="Click checkbox only"
  clickableCard={false}
/>

With Badge

Badges can highlight important information like recommendations or pricing.

Premium PlanRecommended

Access all features with unlimited usage

Basic PlanFree

Essential features for getting started

<CheckboxCard
  label="Premium Plan"
  subtext="Access all features"
  badge="Recommended"
/>

Controlled State

Manage multiple checkbox cards with controlled state for complex selection scenarios.

Selected: option1

Option 1

First option

Option 2

Second option

Option 3

Third option

const [selected, setSelected] = useState<string[]>(['option1'])

const handleChange = (option: string) => (checked: boolean) => {
  if (checked) {
    setSelected([...selected, option])
  } else {
    setSelected(selected.filter(s => s !== option))
  }
}

<CheckboxCard
  label="Option 1"
  checked={selected.includes('option1')}
  onCheckedChange={handleChange('option1')}
/>

All States Overview

Accessibility

Built on Radix UI Checkbox primitive for robust accessibility
Full keyboard support (Space to toggle when focused)
When clickableCard={true}, the entire card is interactive
Proper ARIA attributes for screen readers
Focus states are clearly visible

API Reference

CheckboxCard Props

Prop	Type	Default	Description
label	`string`	-	Required. The main label text
subtext	`string`	-	Secondary descriptive text
badge	`string`	-	Badge text displayed next to the label
variant	`"text" \| "icon" \| "avatar" \| "cardProvider"`	`"text"`	Visual variant
checked	`boolean`	`false`	The controlled checked state
defaultChecked	`boolean`	-	The default checked state (uncontrolled)
onCheckedChange	`(checked: boolean) => void`	-	Callback when checked state changes
disabled	`boolean`	`false`	Whether the card is disabled
error	`boolean`	`false`	Whether to show error styling
clickableCard	`boolean`	`true`	Whether clicking the card toggles the checkbox
icon	`ReactNode`	-	Icon element for the `icon` variant
avatar	`ReactNode`	-	Avatar element for the `avatar` variant
cardProvider	`ReactNode`	-	Provider icon for the `cardProvider` variant
rightSlot	`ReactNode`	-	Custom content in the right slot
className	`string`	-	Additional CSS classes