Overview
CardToggle provides a clear visual selection interface for choosing between a small number (2-4) of mutually exclusive options. Each option is displayed as a card with an icon, label, and optional description, using distinct accent colors for visual differentiation.
Key Features
- Designed for 2-4 options (auto-calculates grid columns)
- Each option has its own accent color for visual distinction
- Icon, label, and optional description per option
- Built on RadioGroup for proper accessibility
- FormBlock integration via formHelpers.cardToggle()
When to Use
Use CardToggle when users must choose exactly one option from a small set. Common use cases include schedule type selection (Calendar vs Journey), access level selection (Public/Team/Private), or mode toggles. For larger sets (5+ options), use CardPicker instead.
Interactive Examples
Two Options
Simple toggle between two options
Three Options
Toggle between three options
Four Options
Toggle between four options
Compact Size
Horizontal inline layout for space-constrained contexts
Use size="compact" for a smaller horizontal layout. Descriptions are hidden in compact mode.
Custom Columns
Override the auto-calculated column count
By default, columns are auto-calculated based on options count. Use the columns prop to override.
Disabled
Toggle in disabled state
Color Variants
Each option can have its own accent color
Available colors: blue, purple, green, red, orange, yellow, pink, cyan, gray
Interfaces
CardToggleOption
| Prop | Type | Description |
|---|---|---|
value | string | Unique identifier for the option |
label | string | Display label for the option |
description | string? | Optional helper text shown below the label |
icon | IconDefinition | Font Awesome icon to display |
color | CardToggleColor | Accent color for icon and selection state |
CardToggleColor
'blue' | 'purple' | 'green' | 'red' | 'orange' | 'yellow' | 'pink' | 'cyan' | 'gray'
CardToggleSize
'default' | 'compact'
Use compact for horizontal inline layout in space-constrained contexts. Descriptions are hidden in compact mode.
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
options | CardToggleOption[] | required | Array of options to display (2-4 recommended) |
value | string | required | Currently selected option value (controlled) |
onChange | (value: string) => void | required | Callback when selection changes |
size | 'default' | 'compact' | 'default' | Size variant: default for stacked cards with descriptions, compact for horizontal inline |
columns | 1 | 2 | 3 | 4 | auto | Override auto-calculated grid columns (1-4) |
disabled | boolean | false | Disable all interactions |
className | string | - | Additional CSS classes for the container |
Usage
import { CardToggle, type CardToggleOption } from '@/ui/components';
import { faCalendarDays, faRoute } from '@fortawesome/duotone-regular-svg-icons';
// Define your options (2-4 recommended)
const options: CardToggleOption[] = [
{
value: 'sync',
label: 'Calendar',
description: 'Fixed calendar dates',
icon: faCalendarDays,
color: 'blue',
},
{
value: 'async',
label: 'Journey',
description: 'Relative to participant join',
icon: faRoute,
color: 'purple',
},
];
// Basic usage
const [selected, setSelected] = useState('sync');
<CardToggle
options={options}
value={selected}
onChange={setSelected}
/>
// Compact size (horizontal inline)
<CardToggle
options={options}
value={selected}
onChange={setSelected}
size="compact"
/>
// With custom columns
<CardToggle
options={options}
value={selected}
onChange={setSelected}
columns={1}
/>