Switch primitive

Use the Switch primitive when your layout owns the label, such as a settings row, or when the label needs custom content. For a normal labelled switch, use SwitchField.

import { InlineField } from '@luke-ui/react/primitives/field';
import {
	SwitchControl,
	SwitchLabel,
	SwitchRoot,
	SwitchThumb,
} from '@luke-ui/react/primitives/switch';

export default () => {
	return (
		<SwitchRoot>
			<InlineField description="Example description">
				<SwitchLabel>
					<SwitchControl>
						<SwitchThumb />
					</SwitchControl>
					Example switch
				</SwitchLabel>
			</InlineField>
		</SwitchRoot>
	);
};

Anatomy

SwitchRoot is the semantic root. It owns the selection, state, validation, form, and size props. id, className, and ref target the root element. inputId and inputRef target the input.

SwitchLabel is the clickable native <label>. It holds the hidden input, SwitchControl, and usually the label text. Like React Aria's SwitchButton, it takes className, style, and children as functions of the switch state, as well as render, slot, and event handlers.

SwitchControl draws the track, and SwitchThumb draws the thumb that moves along it. Pass children to SwitchThumb to draw inside the thumb. Put the control before the label text.

Description and error

Wrap SwitchLabel in InlineField to add a description and an errorMessage. The errorMessage shows while the root is invalid. For a custom arrangement, place FieldDescription and FieldError inside the root instead of InlineField.

Labels from the layout

When another part of the layout draws the visible label and description, leave the text out of SwitchLabel. Place a FieldLabel and a FieldDescription anywhere inside SwitchRoot. The root connects them to the input, so the label names the switch, clicking it toggles the switch, and the description describes it. Pass no ids.

Put the label text in either SwitchLabel or FieldLabel, not both. The switch's name joins the text from each.

import { Box } from '@luke-ui/react/box';
import { FieldDescription, FieldLabel } from '@luke-ui/react/primitives/field';
import {
	SwitchControl,
	SwitchLabel,
	SwitchRoot,
	SwitchThumb,
} from '@luke-ui/react/primitives/switch';
import { Stack } from '@luke-ui/react/stack';

export default () => {
	return (
		<SwitchRoot>
			<Box alignItems="center" display="flex" gap="space.12" style={{ maxInlineSize: '24rem' }}>
				<Stack flexGrow="1" gap="space.4">
					<FieldLabel>Example setting</FieldLabel>
					<FieldDescription>The row draws this label and description.</FieldDescription>
				</Stack>
				<SwitchLabel>
					<SwitchControl>
						<SwitchThumb />
					</SwitchControl>
				</SwitchLabel>
			</Box>
		</SwitchRoot>
	);
};

SwitchLabel is a native <label>, so it takes textual, non-interactive content only. Place links and buttons outside it. Set slot={null} on each Text you place in it, as the Checkbox primitive describes.

SwitchLabel draws no required marker. With isRequired on SwitchRoot, a FieldLabel does, as Required fields describes. Show the required state in your own content when you use SwitchLabel for the text.

API

SwitchRootProps

SwitchLabelProps

SwitchControlProps

SwitchThumbProps