Switch·component·@astryxdesign/core

Switch

A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.

Open in Playground @astryxdesign/core/Switch

Showcases and examples

5 documented examples

Switch

A toggle switch for enabling notifications.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · switch-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Switch} from '@astryxdesign/core/Switch';

export default function SwitchShowcase() {
  const [enabled, setEnabled] = useState(true);
  return (
    <Switch
      label="Enable notifications"
      value={enabled}
      onChange={setEnabled}
    />
  );
}

Usage

Use for settings that apply immediately; the toggle should take effect without a separate save action.
Pair with a clear, concise label that describes the setting being controlled.
Use for options that require a form submission to take effect; use a checkbox instead.
Use a switch for multi-state values; it's strictly on/off.
Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Typed props

Prop	Type and behavior
`ref`	`React.Ref<HTMLInputElement>` Ref forwarded to the underlying <input> element.
`label`	`string` · required Label text for the switch (always rendered for accessibility).
`value`	`boolean` · required Whether the switch is on or off.
`onChange`	`(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void` Callback fired when the switch state changes.
`changeAction`	`(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void \| Promise<void>` Async action fired after onChange. Triggers optimistic UI and shows a loading spinner until the promise resolves.
`isLoading`	`boolean` · default false Whether the switch is in a loading state, showing a spinner inside the thumb.
`isLabelHidden`	`boolean` · default false Visually hides the label while keeping it accessible to screen readers.
`description`	`string` Description text displayed below the label.
`isDisabled`	`boolean` · default false Whether the switch is disabled.
`size`	`'sm' \| 'md'` · default 'md' Size variant controlling track and thumb dimensions. sm (32x20px) matches sm checkbox/radio vertical rhythm; md (40x24px, default) matches md checkbox/radio vertical rhythm.
`htmlName`	`string` The HTML name attribute for the underlying checkbox input, useful for form submissions (submits "on" when the switch is on).
`disabledMessage`	`string` Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
`isOptional`	`boolean` · default false Whether the field is optional. Mutually exclusive with isRequired.
`isRequired`	`boolean` · default false Whether the switch is required. Mutually exclusive with isOptional.
`status`	`{type: 'warning' \| 'error' \| 'success', message?: string}` Status indicator with type and message. Displays a colored message box below the switch and sets aria-invalid when type is "error".
`onFocus`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the switch receives focus.
`onBlur`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the switch loses focus.
`labelIcon`	`IconType` Icon displayed before the label text. See `astryx docs icons` for valid semantic names.
`labelTooltip`	`string` Tooltip text shown in an info icon at the end of the label.
`labelPosition`	`'start' \| 'end'` · default 'end' Which side of the switch the label appears on. "start" places the label before the switch.
`labelSpacing`	`'hug' \| 'spread'` · default 'hug' Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width).
`width`	`SizeValue` Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.

Anatomy

Field · required

Container arranging the switch, label, and feedback.

Track · required

Pill-shaped surface that shows the off or on state.

Thumb · required

Indicator that moves across the track when state changes.

Label · required

Text identifying the setting controlled by the switch.

Description · optional

Helper text below the label.

Spinner · optional

Loading indicator shown inside the thumb while busy.

Status message · optional

Error, warning, or success message below the switch.

Accessibility

Track and thumb

Color contrast · 1.4.11 Non-text Contrast · 3:1

The on and off tracks must each have at least 3:1 contrast with the surface behind them, and the thumb with its track. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.

States: Rest, Hover, Pointer down

Theming

Targets

astryx-switch

Visual props: size

States: checked, disabled

astryx-switch-thumb

Visual props: size

States: checked

astryx-switch-field

Visual props: labelPosition, labelSpacing

astryx-switch-label