CheckboxCard

Summary

CheckboxCard combines checkbox behavior with a richer card surface for plans, templates, and selectable settings tiles. It wraps Card, exposes card-specific content parts, and syncs control state through checkbox-card context. It is the rich-content multi-select option layer when compact checkbox rows are no longer enough.

Imports

import {
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlInput,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardDescription,
  CheckboxCardTitle,
  type CheckboxCardContentProps,
  type CheckboxCardControlCheckedIconProps,
  type CheckboxCardControlInputProps,
  type CheckboxCardControlIndeterminateIconProps,
  type CheckboxCardControlProps,
  type CheckboxCardDescriptionProps,
  type CheckboxCardProps,
  type CheckboxCardTitleProps,
} from '@vega-ui/react';

Exported Types

• CheckboxCardProps
• CheckboxCardContentProps
• CheckboxCardTitleProps
• CheckboxCardDescriptionProps
• CheckboxCardControlProps
• CheckboxCardControlInputProps
• CheckboxCardControlCheckedIconProps
• CheckboxCardControlIndeterminateIconProps

Minimal Composition

import {
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxIndicator,
} from '@vega-ui/react';

Required Parts

• CheckboxCard: root card surface and checkbox-card context
• CheckboxCardContent: text content region
• CheckboxCardControl: control region for input and indicator
• CheckboxCardControlInput: the native checkbox inside the control
• CheckboxIndicator (from Checkbox): the visible box inside the control

Optional Parts

• CheckboxCardTitle
• CheckboxCardDescription
• CheckboxCardControlCheckedIcon
• CheckboxCardControlIndeterminateIcon

Composition Order

1. CheckboxCard
2. CheckboxCardContent
3. CheckboxCardTitle and CheckboxCardDescription
4. CheckboxCardControl
5. CheckboxCardControlInput and CheckboxIndicator with the state icons inside the control

Variants

• Variant: primary, secondary
• Orientation: vertical, horizontal
• State: checked, unchecked, indeterminate, disabled

Edge Cases

• Ensure the card communicates checked and disabled states clearly across the whole surface.
• Give CheckboxCardControlInput a name if the card belongs to a form.
• Long descriptions should not obscure the main selection affordance.
• If the group is actually exclusive, a radio-family or segmented control usually communicates intent better than checkbox cards.

Common Mistakes

• Making only the tiny control clickable instead of the whole card.
• Using checkbox cards for single-select groups that should be radios or segmented controls.
• Letting descriptions dominate the selection affordance.

Examples

Basic

Basic: add-on selection

Several independent cards inside a Fieldset. The whole card is the label, so clicking anywhere toggles it and the title and description become the accessible name. The control is CheckboxCardControl with CheckboxCardControlInput and a CheckboxIndicator holding the state icons.

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

Controlled/Stateful

Controlled/Stateful: selection with a computed total

The parent owns the list of selected extras and passes checked and onChange to each CheckboxCardControlInput. The monthly total is derived from the same state.

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

Form/Integration

Form/Integration: reading values with FormData

Cards with the same name submit every checked value, so FormData.getAll('include') returns the selection. Reset restores defaultChecked on every card.

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

Layout/Overlay

Layout/Overlay: horizontal cards in a settings list

orientation='horizontal' puts the control on the inline end, which suits a vertical list of settings. size='sm' keeps the list dense.

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

Error

Error: at least one card required

Native required cannot express “at least one of the group”, so the check runs on submit. The error is linked to the Fieldset through aria-describedby, the inputs get aria-invalid, and checking any card clears it.

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

Disabled

Disabled: option unavailable on the current plan

A disabled input disables the whole card visually. The description gets an id and the input points to it with aria-describedby, so screen readers hear why the option is unavailable.

import {
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxIndicator,
} from '@vega-ui/react';

Edge

Edge: card summarizing a nested list

The card is checked when every office is enabled and indeterminate when only some are; clicking it toggles all of them. The description counts the enabled offices from the same state.

import { useState } from 'react';
import {
  Checkbox,
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxCheckedIcon,

Edge: long titles and descriptions

CheckboxCardTitle stays on one line and truncates with an ellipsis; the full text is still in the DOM, so the accessible name is complete, and title shows it on hover. Set white-space: normal on the title when it must wrap. Descriptions always wrap.

import {
  CheckboxCard,
  CheckboxCardContent,
  CheckboxCardControl,
  CheckboxCardControlCheckedIcon,
  CheckboxCardControlIndeterminateIcon,
  CheckboxCardControlInput,
  CheckboxCardDescription,
  CheckboxCardTitle,
  CheckboxIndicator,
} from '@vega-ui/react';

Anatomy

Overview

CheckboxCard is a compound selection card. The root renders a labeled card surface, while exported child parts split content, title, description, and control UI.

Required Parts

• CheckboxCard: root labeled card and shared checkbox context
• CheckboxCardContent: content column for the main message
• CheckboxCardControl: control area for the checkbox affordance
• CheckboxCardControlInput: the native checkbox inside the control
• CheckboxIndicator (from Checkbox): the visible box inside the control

Optional Parts

• CheckboxCardTitle
• CheckboxCardDescription
• CheckboxCardControlCheckedIcon
• CheckboxCardControlIndeterminateIcon

Composition Order

1. CheckboxCard
2. CheckboxCardContent
3. CheckboxCardTitle and CheckboxCardDescription
4. CheckboxCardControl
5. CheckboxCardControlInput and CheckboxIndicator with the state icons inside the control

Valid Composition Patterns

• plan tiles where the whole card acts as the checkbox label
• settings cards with a short title and supporting description
• horizontal or vertical layouts depending on density

Invalid Composition Patterns

• making the control clickable but not the surrounding label/card
• using checkbox cards for mutually exclusive single choice
• letting decorative content obscure the actual checked state