Switch Card

Sizes

<SwitchCard size="sm" label="Small" body="Body copy" />

<SwitchCard size="md" label="Medium" body="Body copy" />

States

<SwitchCard label="Rest" body="Body copy" />

<SwitchCard label="Selected" body="Body copy" defaultChecked />

Disabled

<SwitchCard label="Email notifications" body="Body copy" disabled />

<SwitchCard label="Email notifications" body="Body copy" disabled defaultChecked />

With descriptor

<SwitchCard label="Email notifications" body="We will email you when a job is booked." />

<SwitchCard label="Email notifications" descriptor="Optional second line" body="We will email you when a job is booked." />

Hit target

<SwitchCard label="Email notifications" body="Click anywhere on this card." />

When to use

Use a switch card when a single on/off setting needs more room to explain itself than a one-line switch label allows — a title, an optional second line, and a body line of context, all inside one clearly-bounded target.

A switch implies the change has already taken effect, so use it for settings that apply immediately rather than values that are submitted with a form.

When not to use

• A value that is submitted with a form: use a checkbox card. On web that one is a real form control; the switch card is not.
• A short, self-evident label: use a plain switch. A card adds padding for no benefit when there is nothing to explain.
• Rich card content — links, buttons, images, anything interactive: not supported. The card is a single label/pressable, so nested interactive content would be invalid. The three text slots are strings for exactly this reason.
• A group of related settings: compose several cards; a card-list component is not built yet.

Switch Card vs Checkbox Card

The two are the same card with a different control in the corner — same width, same two sizes, same text slots. Pick by what the choice means: a switch card is a setting that takes effect immediately, a checkbox card is a value the user is confirming.

Props

Not available on the card, because it owns them itself: labelPosition and showStateIcon (the card owns the layout and never renders the in-track state icon), and aria-label / aria-labelledby on web (the name is derived from label and descriptor).

The card’s props are derived from SwitchProps: it is Omit<SwitchProps, 'label' | 'labelPosition' | 'showStateIcon' | 'aria-label'> plus the required label and body slots and its own descriptor (Switch has no descriptor slot). Any prop Switch accepts — size, id and the rest — is accepted here too, and a prop added to Switch reaches SwitchCard without a second edit.

Import

Web

import { SwitchCard } from '@checkatrade/components-web';

Native

import { SwitchCard } from '@checkatrade/components-native';

Basic usage

Controlled (both platforms):

const [on, setOn] = useState(false);
<SwitchCard
  label="Email notifications"
  body="We will email you when a job is booked."
  checked={on}
  onChange={setOn}
/>;

Uncontrolled (both platforms):

<SwitchCard label="Email notifications" body="Body copy" defaultChecked />

With the optional descriptor:

<SwitchCard
  label="Email notifications"
  descriptor="Optional second line"
  body="We will email you when a job is booked."
/>

Platform status

The Figma source is marked Caution because the selected border resolves to a different value than Figma draws, the rest stroke is ahead of Figma, and the switch track sizes in the card spec do not match the shipped switch — see Token gaps below.

Accessibility

Web

• The card is a <label> wrapping the text block and the control, so the whole card is a click target — clicking the label, descriptor or body toggles the switch exactly once. A <label> can label a <button>, which is what makes this work for the switch’s control.
• The control keeps its own semantics: a <button role="switch">, focusable and toggled with Space/Enter. The card does not add a second announcement.
• The accessible name is the label plus the descriptor, joined as "label. descriptor". The body is exposed as the accessible description, not concatenated into the name.
• The focused state is a 4px focus-ring outline drawn outside the card, and appears on keyboard focus rather than mouse click.

React Native

• The card’s root Pressable is not an accessibility node and is not a tab stop, so it adds no second announcement.
• The control keeps its own semantics: accessibilityRole="switch" with accessibilityState={{ checked, disabled }}.
• Native has no accessible-description slot, so the name is the label, descriptor and body joined with a full stop — e.g. "Email notifications. Optional second line. Body copy". A consumer accessibilityLabel overrides it outright.
• The text block and the body are visible but hidden from assistive tech on both native and the web surface, so the control stays the single source of the accessible name.
• The whole card is the tap target. Pressing the text or the body toggles the control exactly once.

Target size

The whole card is the target on both platforms, so the effective hit area is far larger than the switch track at every size.

Token gaps

• Native Text cannot take the card’s label tokens. Web colours the label, descriptor and body from the selector label tokens in every state. Native Text has no colour escape hatch, so native keeps the default ink and dims a disabled card’s text instead.
• The switch track sizes in the card spec do not match the shipped switch. The spec’s extraction measured the control at 40 × 24 / 56 × 32 / 70 × 40; the shipped switch is 44 × 24 / 60 × 32 / 80 × 40, and the card renders the real switch. The shipped values are what the component uses. Raised with Design.
• No surface-tone-aware card tokens. The card’s selector tokens have no inverse counterpart, so inside an inverse surface the card keeps its normal-surface colours. This applies to the control’s tokens too.
• The selected border is a close match, not an exact one. Figma draws it at #0036fa; the card binds --color-selector-border-selected, which resolves to #040154. The token is what the card uses — there is no literal — and the difference is a deliberate deviation signed off with Design.
• The native card and the web card are close but not identical. Fill, border, hover and the selected and disabled states match. Native cannot apply the label tokens, so its text does not recolour on hover or selection, and a disabled card dims its text instead.

No releases yet.