# Switch primitive (/components/primitives/switch)



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`](/components/forms/switch-field).

apps/docs/src/examples/switch-primitive/basic.tsx

```tsx
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 [#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 [#description-and-error]

Wrap `SwitchLabel` in [`InlineField`](/components/primitives/field) 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 [#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`](/components/primitives/field) 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.

apps/docs/src/examples/switch-primitive/external-label.tsx

```tsx
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="sp12" maxInlineSize="24rem">
				<Stack flexGrow="1" gap="sp4">
					<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](/components/primitives/checkbox#text-in-the-label) describes.

`SwitchLabel` draws no required marker. With `isRequired` on `SwitchRoot`, a `FieldLabel` does, as
[Required fields](/components/forms/text-input-field#required-fields) describes. Show the required
state in your own content when you use `SwitchLabel` for the text.

## API [#api]

### SwitchRootProps [#switchrootprops]

### SwitchRootProps

Props for `SwitchRoot`.

`SwitchRootProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

| Prop                  | Type                         | Description                                                                                                                                                                                                      |
| --------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aria-label?`         | `string`                     | Defines a string value that labels the current element.                                                                                                                                                          |
| `aria-labelledby?`    | `string`                     | Identifies the element (or elements) that labels the current element.                                                                                                                                            |
| `aria-describedby?`   | `string`                     | Identifies the element (or elements) that describes the object.                                                                                                                                                  |
| `aria-details?`       | `string`                     | Identifies the element (or elements) that provide a detailed, extended description for the object.                                                                                                               |
| `aria-errormessage?`  | `string`                     | Identifies the element that provides an error message for the object.                                                                                                                                            |
| `onKeyDown?`          | `function`                   | Handler that is called when a key is pressed.                                                                                                                                                                    |
| `onKeyUp?`            | `function`                   | Handler that is called when a key is released.                                                                                                                                                                   |
| `onFocus?`            | `function`                   | Handler that is called when the element receives focus.                                                                                                                                                          |
| `onBlur?`             | `function`                   | Handler that is called when the element loses focus.                                                                                                                                                             |
| `onFocusChange?`      | `function`                   | Handler that is called when the element's focus status changes.                                                                                                                                                  |
| `onPress?`            | `function`                   | Handler that is called when the press is released over the target.                                                                                                                                               |
| `onPressStart?`       | `function`                   | Handler that is called when a press interaction starts.                                                                                                                                                          |
| `onPressEnd?`         | `function`                   | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.                                                                                              |
| `onPressChange?`      | `function`                   | Handler that is called when the press state changes.                                                                                                                                                             |
| `onPressUp?`          | `function`                   | Handler that is called when a press is released over the target, regardless of whether it started on the target or not.                                                                                          |
| `autoFocus?`          | `union`                      | Whether the element should receive focus on render.                                                                                                                                                              |
| `slot?`               | `union`                      | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `children`            | `ChildrenOrFunction<object>` | Switch anatomy: `SwitchLabel`, plus a `FieldLabel`, a description, and an error such as `InlineField`.                                                                                                           |
| `className?`          | `union`                      | Class name for the root element.                                                                                                                                                                                 |
| `defaultSelected?`    | `union`                      | Initial selection state for an uncontrolled switch.                                                                                                                                                              |
| `form?`               | `string`                     | The `<form>` element to associate the input with, by id.                                                                                                                                                         |
| `id?`                 | `string`                     | Element id for the root element. Use `inputId` for the input.                                                                                                                                                    |
| `inputId?`            | `string`                     | Element id for the input and the `for` of a `FieldLabel` in the root. Defaults to a generated id.                                                                                                                |
| `inputRef?`           | `union`                      | Forwarded to the underlying `<input type="checkbox" role="switch">` element.                                                                                                                                     |
| `isDisabled?`         | `union`                      | Whether the switch is disabled.                                                                                                                                                                                  |
| `isInvalid?`          | `union`                      | Marks the switch invalid, for example after failed validation.                                                                                                                                                   |
| `isReadOnly?`         | `union`                      | Whether the switch can be read but not changed.                                                                                                                                                                  |
| `isRequired?`         | `union`                      | Whether the switch must be on before the form can submit.                                                                                                                                                        |
| `isSelected?`         | `union`                      | Whether the switch is on.                                                                                                                                                                                        |
| `name?`               | `string`                     | The name of the input, used when submitting an HTML form.                                                                                                                                                        |
| `onChange?`           | `function`                   | Called when the switch turns on or off.                                                                                                                                                                          |
| `ref?`                | `union`                      | Forwarded to the root element.                                                                                                                                                                                   |
| `size?`               | `union`                      | Visual size of the switch control. Default: `'medium'`                                                                                                                                                           |
| `validate?`           | `function`                   | Custom validation function run against the selection. Return a message, or `true`/`null` when valid.                                                                                                             |
| `validationBehavior?` | `union`                      | When native HTML form validation runs. Default: `'native'`                                                                                                                                                       |
| `value?`              | `string`                     | The value submitted with an HTML form when the switch is on.                                                                                                                                                     |


### SwitchLabelProps [#switchlabelprops]

### SwitchLabelProps

Props for `SwitchLabel`.

`SwitchLabelProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

| Prop             | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onHoverStart?`  | `function`                           | Handler that is called when a hover interaction starts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `onHoverEnd?`    | `function`                           | Handler that is called when a hover interaction ends.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `onHoverChange?` | `function`                           | Handler that is called when the hover state changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `slot?`          | `union`                              | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.                                                                                                                                                                                                                                                                                                             |
| `render?`        | `DOMRenderFunction<"label", object>` | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `children`       | `ChildrenOrFunction<object>`         | `SwitchControl` plus textual, non-interactive label content, unless a `FieldLabel` supplies the label. Pass a function to render from the switch state.                                                                                                                                                                                                                                                                                                                                                                      |
| `ref?`           | `union`                              | Forwarded to the `<label>` element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |


### SwitchControlProps [#switchcontrolprops]

### SwitchControlProps

Props for `SwitchControl`.

`SwitchControlProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

### SwitchThumbProps [#switchthumbprops]

### SwitchThumbProps

Props for `SwitchThumb`.

`SwitchThumbProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.