Switch

Import

import { Switch } from '@envsemble/envui';

Usage

<Switch label="Show completed tasks" checked={showCompleted} onCheckedChange={setShowCompleted} />

A Switch is a native checkbox with role="switch", named by its label; an optional description is a short muted line under it, read with its name. Apply the setting from onCheckedChange, which receives the new state; control it with checked, or leave it uncontrolled with defaultChecked, which a form reset restores. When saving fails, set it back. name and the other native props reach the input.

Disabled

<Switch label="Two-step sign-in" defaultChecked disabled aria-describedby={reason} />
<Text id={reason} variant="body-sm">
  Your administrator, Sam Lee, manages these settings for everyone at Northwind.
</Text>

Settings in a list

In a List row, the row's title names the switch through aria-labelledby, and its detail describes it through aria-describedby, as the SettingsRows example does.

Composition

The root, env-switch, is the label around the track, env-switch-input, and the text, env-switch-label. className and style reach the root, and ref and the other native props the input.

Accessibility

You provide

A label, or aria-labelledby where the name shows elsewhere.
A description linked with aria-describedby where a setting needs explaining.
An announcement, such as a Toast, where the change happens out of sight or fails.

envUI provides

A native checkbox with role="switch", announced as on or off.
A <label> that names the switch and toggles it when pressed.
An off track whose edge reaches 3:1 contrast, and a 2.75 rem target on touch screens.

Props

An on/off setting that takes effect at once: a native checkbox with the switch role, drawn as a track and a thumb, with its label beside it.

Prop	Type	Description
`ref`	`Ref<HTMLInputElement>`	The native checkbox with the switch role, so that a form library can register it and focus it; the other native props, such as name, reach it too.
`className`	`string`	The switch's class, on its root element, the label around the track and the text.
`style`	`CSSProperties`	Styles of the root element.
`label`	`ReactNode`	The setting the switch turns on or off, such as Show completed tasks, beside the track. It names the switch, stays the same in both states, and pressing it toggles the switch too. Without it, name the switch with aria-label or aria-labelledby.
`description`	`ReactNode`	A short, muted line under the label, such as what the option changes. It is part of the switch's label, so it is read with its name.
`checked`	`boolean`	Whether a controlled switch is on; update it from onCheckedChange.
`defaultChecked`Default `false`	`boolean`	Whether an uncontrolled switch starts on; a native form reset returns it to this state.
`onCheckedChange`	`(checked: boolean) => void`	Receives the new state each time people turn the switch on or off.

Also accepts the native props of <input>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-switch: The switch with its label.
env-switch-description: The muted line under the label.
env-switch-input: The native input.
env-switch-label: The label.

Color properties

Each sets a color of one instance, through style or CSS; its hover, focus and press follow it. They are public and versioned.

--env-switch-container: The track while off; the state layers lie over it.
--env-switch-content: The thumb while off, and the color of the state layers.
--env-switch-outline: The track's ring while off.
--env-switch-selected: The track while on; set, it takes state layers instead of the designed hover and press fills.
--env-switch-selected-content: The thumb while on.

Changelog

1.0.0: className and style style the root, env-switch, rather than the input, which keeps ref and the other native props. env-choice-control is env-switch and env-switch-control env-switch-input.

The track of a switch that is off has a 3:1 boundary, and switches in the dark theme reach 3:1 on every surface.
1.0.0-prerelease.6: Colors under the pointer and while pressed change with --env-motion-ease-enter, rather than easing in slowly, so hover and press show from the first frame.

The thumb's color changes with the track's as it slides.

A switch that is on and unavailable keeps its fill and its white thumb, faded with its label, rather than a faint tint with a gray thumb, which read as off.

A switch that is off has a muted thumb, which no longer outweighs one that is on, and darkens it under the pointer with its ring. A switch that is on and unavailable takes a faint tint of the accent, --env-color-bg-primary-muted, rather than the neutral fill, so it differs from one that is off by more than the thumb's place.

A switch that is on that is unavailable takes the neutral fill, with its thumb in --env-color-fg-disabled, rather than a faded accent, as an unavailable button does.

Beside a label that wraps or has a description, the track sits on the middle of its first line rather than across both lines.

Under the pointer and while pressed, a halo of the shared state layer rings the track, on or off, a step stronger while pressed; a switch that is off also darkens its ring, as its track deepens.
1.0.0-prerelease.5: description, a muted line under the label.