Switch Group

Description

SwitchGroup is a horizontal form-field row: one Switch, a label/description block, and an optional footer for helper text. It wraps the in-house Field (which provides the labelled layout) and cascades variant, size, shape, thumbType, and ioTrigger to the child Switch through SwitchContext, so you configure the look once on the group instead of on every row.

Reach for it when a live setting needs a real label: notification preferences, feature flags, privacy toggles. The switch commits the change the moment it flips, so the row reads as "this is on now," not "this will apply when I submit." Stack several rows in a column for a settings panel and the cascade keeps every switch visually aligned.

Don't use it inside a form that only saves on an explicit submit; reach for Checkbox or CheckboxGroup there. Don't use it for one-of-many selection; that's RadioGroup. For a bare toggle in a toolbar or table cell with no label, drop down to Switch directly and skip the Field layout.

Installation

pnpm dlx @create-ui/cli add switch-group

Anatomy

SwitchGroup composes Field around one Switch and its label content. The label block lives inside FieldContent so the description and footer stay aligned with the switch's first line.

<SwitchGroup>
  <Switch id="…" />
  <FieldContent>
    <LabelMain>
      <Label htmlFor="…" />
      <LabelDescription />
    </LabelMain>
    <FieldFooter />
  </FieldContent>
</SwitchGroup>

Usage

import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"
import { SwitchGroup } from "@/components/ui/switch-group"

<SwitchGroup>
  <Switch id="alerts" defaultChecked />
  <Label htmlFor="alerts">Email alerts</Label>
</SwitchGroup>

Examples

Variants

variant sets the track color and cascades to the child Switch. Five options: primary (default), info, neutral, inverse for dark surfaces, and semantic (red when off, green when on).

Sizes

size scales the switch and the label together through Field and SwitchContext. Pick xs for dense settings tables and md when the row stands alone.

Placement

placement="left" (default) puts the switch before the label. placement="right" flips the row direction without changing DOM order, which is useful when aligning switches against a right-hand edge.

Thumb Type

thumbType cascades to the child Switch. short (default) is a compact knob; long widens the thumb and extends its travel for a more tactile feel.

I/O Trigger

ioTrigger cascades to the child Switch, rendering a pipe glyph when on and a circle when off inside the track. Use it when color alone should not carry the state.

Thumb Icon

thumbIcon on the child Switch shows a check icon on the thumb when on and a close icon when off. Set it per switch; unlike ioTrigger, it does not cascade from the group.

Disabled

disabled on the group sets the Field context's disabled flag, which fades the label and description and blocks pointer events on the row. Pass disabled on the child Switch too so it leaves the tab order.

Accessibility

SwitchGroup delegates all focus and ARIA behavior to its child Switch; the wrapping Field is a role="group" div, not a control. Keyboard interaction lives on the switch.

ARIA notes:

• The root <div> is role="group" and exposes data-invalid, data-disabled, and data-loading so the label, description, and footer restyle through Tailwind group selectors.
• Always pair the child Switch id with the Label htmlFor so screen readers announce what the toggle controls.
• The glyphs rendered by ioTrigger (and any thumb icons) are aria-hidden="true" and do not affect the accessible name.

Styling

Tailwind override: pass className to merge Tailwind classes on the root Field row:

<SwitchGroup className="w-[340px]" />

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="switch-group" on the root.
• data-variant="<variant>", data-placement="<placement>", data-shape="<shape>", data-thumb-type="<thumbType>" on the root.
• Inherited from Field: data-slot="field", data-size, data-orientation="horizontal", data-invalid, data-disabled, data-loading.

Target the right-aligned layout in CSS:

[data-slot="switch-group"][data-placement="right"] {
  flex-direction: row-reverse;
}

Related Components

• Switch: the bare toggle without label or footer; use it directly in toolbars and table cells.
• CheckboxGroup: use when the row belongs to a form that saves on submit, or needs an indeterminate state.
• RadioGroup: single-select alternative for picking one option from a set.
• Field: the lower-level form-field wrapper this component composes; reach for it when you need a different layout.

API Reference

SwitchGroup

A horizontal Field that wraps one Switch plus its label content and cascades switch styling through context. Extends React.ComponentProps<typeof Field> minus the orientation and size props (which are managed internally), so other Field props (invalid, loading, disabled, …) pass through.

Props

Variants