Overview
CardSwitch elevates binary on/off settings with the same visual treatment that CardToggle gives to multi-option selection. Each switch displays as a card with an icon, always-visible description, and color-coded active state. When enabled, switches can reveal additional configuration options inline. The entire card is clickable.
Key Features
- Entire card is clickable - not just the switch
- Icon + label + always-visible description
- 4 semantic colors (default gray + success/warning/danger)
- Expandable content when switch is ON
- Built on Radix Switch for accessibility
- FormBlock integration via FormCardSwitchField
When to Use
Use CardSwitch when binary settings need visual weight - when the setting has implications users should understand, when color can communicate meaning (security, automation, etc.), or when enabling reveals additional options. For simple switches in dense settings panels, use FormSwitchField instead.
Color Semantics
Most switches should omit the color prop entirely, using the default gray styling. Only add color when it communicates specific meaning to the user.
Interactive Examples
Default (No Color)
Most switches should omit color - uses default gray styling
Show this resource in the participant's quick access menu
Show additional configuration options for power users
Default switches blend into the UI naturally. Use this for most settings where color doesn't add meaning.
Semantic Colors
Only 4 semantic colors - use them when color communicates meaning
Participants can edit their submissions after completion
Participants must complete this resource before proceeding
Allow anyone with the link to view this resource
success (green) - Enabling helpful featureswarning (orange) - Important, requires attentiondanger (red) - Security-critical or destructiveGrid Layout (2 Columns)
Two switches per row for compact settings panels
Receive updates via email
Show notifications in the app
grid gap-3 sm:grid-cols-2Grid Layout (3 Columns)
Three switches per row for dashboard-style layouts
Track usage metrics
Require 2FA for login
Log all user actions
grid gap-3 sm:grid-cols-2 lg:grid-cols-3With Expandable Content
Switch that reveals additional options when enabled
Send follow-up reminders to participants who haven't completed
Comma-separated days after availability (e.g., 1, 3, 7)
CardSwitchGroup
Multiple related switches grouped together
Configure notifications when this resource is published
Notify participants when this resource becomes available
Send follow-up reminders for incomplete submissions
Allow anyone with the link to view this resource
Note: Only the security-critical "Public Access" switch has a color. The others use default styling since they don't need semantic emphasis.
Disabled
Switch in disabled state
Participants can edit their submissions after initial completion
Interfaces
CardSwitchColor
'default' | 'success' | 'warning' | 'danger'
Props Reference
CardSwitch
| Prop | Type | Default | Description |
|---|---|---|---|
icon | IconDefinition | required | Font Awesome icon to display |
label | string | required | Switch label text |
description | string | required | Description text (always visible) |
color | CardSwitchColor | 'default' | Semantic color for active state. Most switches should omit this. |
checked | boolean | required | Controlled checked state |
onCheckedChange | (checked: boolean) => void | required | Callback when switch changes |
disabled | boolean | false | Disable the switch |
children | ReactNode | - | Expandable content shown when checked |
className | string | - | Additional CSS classes |
id | string | - | HTML id for accessibility |
CardSwitchGroup
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | - | Group title |
description | string | - | Group description |
icon | IconDefinition | - | Icon for group header |
children | ReactNode | required | CardSwitch components |
className | string | - | Additional CSS classes |
Usage
import { CardSwitch, CardSwitchGroup } from '@/ui/components';
import { faLock, faBell, faGlobe } from '@fortawesome/duotone-regular-svg-icons';
// Basic usage - no color (most common)
const [pinned, setPinned] = useState(false);
<CardSwitch
icon={faThumbtack}
label="Pin to Menu"
description="Show in quick access menu"
checked={pinned}
onCheckedChange={setPinned}
/>
// With semantic color (only when color adds meaning)
<CardSwitch
icon={faGlobe}
label="Public Access"
description="Anyone with the link can view"
color="danger" // red - security-critical
checked={isPublic}
onCheckedChange={setIsPublic}
/>
// With expandable content
<CardSwitch
icon={faBell}
label="Enable Reminders"
description="Send follow-up reminders"
checked={remindersEnabled}
onCheckedChange={setRemindersEnabled}
>
<Input label="Days" value={days} onChange={setDays} />
</CardSwitch>