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
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'
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 |
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/sharp-duotone-light-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}
/>
// With custom columns
<CardToggle
options={options}
value={selected}
onChange={setSelected}
columns={1}
/>