# Switch
Turn a setting on or off.
Use a switch for a setting that takes effect as soon as it changes, like Airplane mode or a notification preference. Keep its label the same in both states: the label says what the setting is, and the switch shows whether it's on.
```ts title="basic.ts"
import "@ui-sdk/web/switch"
function mount(root: HTMLElement) {
root.innerHTML = `
`
}
export { mount }
```
Click Airplane mode, or focus the switch and press Space, to turn it on and off.
## Installation
```bash
npm install @ui-sdk/web @ui-sdk/core
```
Importing the component defines its elements. Import the field too if you use it. On the server the import does nothing.
```ts
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
```
## Composition
Use the following composition to build a `ui-switch`:
```text
ui-switch
└── ui-switch-thumb
```
Wrap the switch and its text in a label. The thumb stays mounted and gets the switch's state, so CSS can slide it from one end to the other.
## Usage
Import the parts and put them together:
```html
```
## Description
Use `ui-field-label` and `ui-field-description` inside a `ui-field` when a setting needs more explanation. The field connects both to the switch.
```ts title="description.ts"
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
function mount(root: HTMLElement) {
root.innerHTML = `
Weekly digestA summary of your week, every Monday.
`
}
export { mount }
```
Click Weekly digest. The field connects the label and description to the switch.
## Choice Card
A setting can fill a whole card. Here the label's `::after` covers the card, so a click anywhere on it toggles the switch, and `:has([data-checked])` marks the cards that are on.
```ts title="choice-card.ts"
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
const settings = [
{
label: "Public profile",
description: "Anyone can see your name and photo.",
defaultChecked: false,
},
{
label: "Show activity status",
description: "Teammates can see when you're online.",
defaultChecked: true,
},
]
function mount(root: HTMLElement) {
root.innerHTML = `
${settings
.map(
(setting) => `
${setting.label}${setting.description}
`
)
.join("")}
`
}
export { mount }
```
Click anywhere on the Public profile card to turn it on. Each card's switch keeps its own value.
## Disabled
`disabled` prevents focus and changes, and leaves the switch out of form submissions. A disabled `fieldset` does the same.
```ts title="disabled.ts"
import "@ui-sdk/web/switch"
function mount(root: HTMLElement) {
root.innerHTML = `
`
}
export { mount }
```
Security alerts are always on, so that switch is disabled. Clicking it leaves it on, and Tab skips it.
## Read-Only
`read-only` keeps the switch focusable and included in form submissions, while preventing the user from changing it. Use it for a setting managed somewhere else.
```ts title="read-only.ts"
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
function mount(root: HTMLElement) {
root.innerHTML = `
Encrypt backupsYour organization manages this setting.
`
}
export { mount }
```
Tab to Encrypt backups. Space and clicks leave it on.
## Controlled
Listen for `checkedchange` to follow the value, and set the element's `checked` property to change it. The element's [`api`](#controller) changes it from anywhere, like the Toggle button below. See [State and Events](/docs/web-components/state-and-events) for the shared change callback.
```ts title="controlled.ts"
import "@ui-sdk/web/switch"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const wifi = root.querySelector("ui-switch")!
root
.querySelector("button")!
.addEventListener("click", () => wifi.api.toggle())
wifi.addEventListener("checkedchange", (event) => {
const { value, reason } = event.detail
log(root, `${value ? "On" : "Off"} (${reason})`)
})
}
export { mount }
```
Turn Wi-Fi off, or press Toggle. The console logs each change and its reason.
## Form
Set `name` to include the switch in a native form. A switch that's on submits its `value`, which defaults to `"on"`; a switch that's off submits nothing. Reset returns it to `default-checked`. Set `form` to a form's id to join it from elsewhere on the page.
```ts title="form.ts"
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const form = root.querySelector("form")!
form.addEventListener("submit", (event) => {
event.preventDefault()
const entries = [...new FormData(form)].map(
([name, value]) => `${name}=${value}`
)
log(
root,
entries.length ? `Submitted ${entries.join("&")}` : "Submitted nothing"
)
})
}
export { mount }
```
Turn on Product updates and press Save. The console logs the submitted values, and Reset restores the defaults.
## Validation
`required` blocks submission until the switch is on. In a [Field](/docs/web-components/components/field), `ui-field-error` shows the message under the switch and connects it to the switch. [Forms and Validation](/docs/web-components/forms) covers the shared field behavior.
```ts title="invalid.ts"
import "@ui-sdk/web/switch"
import "@ui-sdk/web/field"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const form = root.querySelector("form")!
form.addEventListener("submit", (event) => {
event.preventDefault()
log(root, `Submitted two-factor=${new FormData(form).get("two-factor")}`)
})
}
export { mount }
```
Press Continue with the switch off to see the error. Turn on Two-factor authentication and continue; the console logs the submitted value.
## Saving on Toggle
To save a change before it shows, call `event.preventDefault()` in `checkedchange` to keep the current value while the save runs. When it finishes, call `api.setChecked(next, { reason: "imperative" })`, and let that reason through in the listener so the saved value commits.
The example ignores presses while a save is running, and shows a spinner in the thumb. `aria-busy` tells assistive technology the switch is busy; the listener is what blocks another change.
```ts title="async.ts"
import "@ui-sdk/web/switch"
import { createElement, LoaderCircle } from "lucide"
import { log } from "./log"
const save = (_checked: boolean) =>
new Promise((resolve) => setTimeout(resolve, 800))
function mount(root: HTMLElement) {
root.innerHTML = `
`
const backups = root.querySelector("ui-switch")!
const thumb = root.querySelector("ui-switch-thumb")!
let saving = false
backups.addEventListener("checkedchange", (event) => {
const { value, reason } = event.detail
if (reason === "imperative") {
return
}
event.preventDefault()
if (saving) {
return
}
saving = true
backups.setAttribute("aria-busy", "true")
thumb.replaceChildren(
createElement(LoaderCircle, {
"data-slot": "spinner",
"aria-hidden": "true",
})
)
log(root, "Saving…")
save(value).then(() => {
saving = false
backups.api.setChecked(value, { reason: "imperative" })
backups.setAttribute("aria-busy", "false")
thumb.replaceChildren()
log(root, `Saved: ${value ? "on" : "off"}`)
})
})
}
export { mount }
```
Turn on Automatic backups. The thumb shows a spinner while it saves, then the switch turns on.
## Custom Rendering
Elements have no render functions. `ui-switch` is the focusable control and `ui-switch-thumb` holds whatever you put inside it. Here a `checkedchange` listener puts a sun or a moon in the thumb, and the stylesheet can read `data-checked` on either part. See [Parts and Composition](/docs/web-components/parts-and-composition) for the rendering contract.
```ts title="render.ts"
import "@ui-sdk/web/switch"
import { createElement, Moon, Sun } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const darkMode = root.querySelector("ui-switch")!
const thumb = root.querySelector("ui-switch-thumb")!
const render = (checked: boolean) =>
thumb.replaceChildren(
createElement(checked ? Moon : Sun, { "aria-hidden": "true" })
)
render(darkMode.checked)
darkMode.addEventListener("checkedchange", (event) =>
render(event.detail.value)
)
}
export { mount }
```
Turn on Dark mode. The thumb renders a sun or a moon from its state.
## Styling
Style the switch and its thumb with `data-checked` and `data-unchecked`, and use `data-disabled`, `data-readonly` and `data-required` for the rest. In an invalid field, the switch also gets `data-invalid` and `aria-invalid`; the thumb doesn't. Slide the thumb with `translate` on `data-checked`, and reverse it under `dir="rtl"`.
Each part has a `data-slot`, such as `switch`, and its state attributes are listed under [Data Attributes](#data-attributes).
## Data Attributes
### ``
`[data-slot="switch"]`
- `data-checked`: Present while on.
- `data-disabled`: Present when disabled, by its own prop or a `