CheckboxCard

(A) One-liner

CheckboxCard is a selection UI where "the entire card acts like a checkbox." For single cards, it works with checked/defaultChecked/onCheckedChange, and in groups, CheckboxCardGroup context manages multiple selection based on value.

(B) Installation (Track A / Track B)

Track A (CLI / local install)

1. Add CheckboxCard

pnpm dlx @fleet-ui/cli add CheckboxCard

2. Import example

import { CheckboxCard, CheckboxCardGroup } from '@fleet-ui/local/components';

Track B (NPM package)

1. Import example

import { CheckboxCard, CheckboxCardGroup } from '@fleet-ui/components';

(D) Core Features & Usage

D-1. Most Common Scenario (Minimal Example: Single)

import { CheckboxCard } from '@fleet-ui/components';
 
export function Example() {
  return (
    <CheckboxCard
      title="Save as default address"
      description="Use this as default shipping address for future orders."
      defaultChecked={false}
      onCheckedChange={(checked) => console.log({ checked })}
    />
  );
}

D-2. Group Usage: CheckboxCardGroup + value

In groups, each card is identified by value, and the group manages multiple selection with values/defaultValues/onValuesChange.

import { useState } from 'react';
import { CheckboxCard, CheckboxCardGroup } from '@fleet-ui/components';
 
export function Example() {
  const [values, setValues] = useState<string[]>(['a']);
 
  return (
    <CheckboxCardGroup
      values={values}
      onValuesChange={setValues}
      min={0}
      max={2}
      gap="md"
    >
      <CheckboxCard value="a" title="Option A" description="Description" />
      <CheckboxCard value="b" title="Option B" description="Description" />
      <CheckboxCard value="c" title="Option C" description="Description" />
    </CheckboxCardGroup>
  );
}

D-3. Style Changes Based on Selection State (Selected props)

CheckboxCard provides these for visual emphasis when selected:

• selectedColorScheme: Change colorScheme on selection
• selectedVariant: Change card variant on selection
• indicatorSelectedVariant: Change checkbox indicator variant on selection

(E) Internal State / Shared Value / Animation

E-1. State Model (Priority: Group > Controlled > Uncontrolled)

Implementation check state priority is as follows:

1. When Group + value provided: Use group context (isSelected(value))
2. Otherwise if checked exists: controlled
3. If neither: uncontrolled internal state based on defaultChecked

Also, disabled is combined value of:

• Card's own disabled
• Group disabled
• When using group: If max is reached and current card is unselected (= cannot add selection), treated as disabled

E-2. Reanimated / Shared Value

Uses shared value for card press interaction and color transition.

• press-in: Spring animation scale to 0.96, opacity to 0.7
• press-out: scale/opacity return to 1
• On selection state change: Transition background/border color with animation spring

Caution: Internal opacity animation is used, so layering additional opacity/scale animation externally may appear different than expected.

(F) Accessibility

CheckboxCard treats the entire card as checkbox.

• Default role: accessibilityRole="checkbox"
• Label: accessibilityLabel || title
• State passed: accessibilityState: { checked, disabled }

Recommended rules:

• When composing custom header/slot where title isn't visible on screen, specifying accessibilityLabel is recommended.

(G) Props Table

Reference: Public types from packages/components/src/CheckboxCard/CheckboxCard.types.ts.

CheckboxCard — CheckboxCardProps

CheckboxCardGroup — CheckboxCardGroupProps