Switch

A control that indicates whether a setting is on or off.

Notifications

<script lang="ts">
	import { Switch } from '@sveltery/base/switch';
</script>

<label class="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
	<Switch.Root
		defaultChecked
		class="flex h-5 w-9 shrink-0 border border-neutral-950 bg-white p-0.5 transition-colors duration-150 ease-[ease] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 data-checked:bg-neutral-950 dark:border-white dark:bg-neutral-950 dark:focus-visible:outline-white dark:data-checked:bg-white"
	>
		<Switch.Thumb
			class="size-3.5 bg-neutral-950 transition-[translate,background-color] duration-150 ease-[ease] data-checked:translate-x-4 data-checked:bg-white dark:bg-white dark:data-checked:bg-neutral-950"
		/>
	</Switch.Root>
	Notifications
</label>

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See Labeling a switch and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

<script lang="ts">
	import { Switch } from '@sveltery/base/switch';
</script>

<Switch.Root>
	<Switch.Thumb />
</Switch.Root>

Examples

Labeling a switch

An enclosing <label> is the simplest labeling pattern:

Wrapping a label around a switch

<label>
	<Switch.Root />
	Notifications
</label>

Rendering as a native button

By default, <Switch.Root> renders a <span> element to support enclosing labels. Prefer rendering the switch as a native button when using sibling labels (for/id).

Sibling label pattern with a native button

<div>
	<label for="notifications-switch">Notifications</label>
	<Switch.Root id="notifications-switch" nativeButton>
		{#snippet render(props, state, children)}
			<button type="button" {...props}>{@render children?.()}</button>
		{/snippet}
		<Switch.Thumb />
	</Switch.Root>
</div>

Native buttons with wrapping labels are supported by using the render snippet to avoid invalid HTML, so the hidden input is placed outside the label:

Render snippet

<Switch.Root nativeButton>
	{#snippet render(props, state, children)}
		<label>
			<button type="button" {...props}>{@render children?.()}</button>
			Notifications
		</label>
	{/snippet}
</Switch.Root>

Form integration

Use Field to handle label associations and form integration:

Using Switch in a form

<Form>
	<Field.Root name="notifications">
		<Field.Label>
			<Switch.Root />
			Notifications
		</Field.Label>
	</Field.Root>
</Form>

API reference

Root

Represents the switch itself. Renders a <span> and a hidden checkbox beside it.

checked boolean false

Name: checked
Description: Whether the switch is currently active. Use bind:checked to share it with the parent.
Type: boolean
Default: false
Binding: bind:checked

defaultChecked boolean false

Name: defaultChecked
Description: The state an empty checked starts from, as on an HTML checkbox.
Type: boolean
Default: false

disabled boolean | null false

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | null
Default: false

readonly boolean | null false

Name: readonly
Description: Whether the user should be unable to activate or deactivate the switch.
Type: boolean | null
Default: false

required boolean | null false

Name: required
Description: Whether the user must activate the switch before submitting a form.
Type: boolean | null
Default: false

nativeButton boolean false

Name: nativeButton
Description: Whether the host is a native <button>. Set true and render a <button>. The id is then applied to that button instead of the hidden input.
Type: boolean
Default: false

name string | null —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | null

value string —

Name: value
Description: The value submitted with the form when the switch is on. By default, the switch submits "on", matching a native checkbox.
Type: string

uncheckedValue string —

Name: uncheckedValue
Description: The value submitted with the form when the switch is off. By default, an unchecked switch does not submit a value.
Type: string

form string | null —

Name: form
Description: Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
Type: string | null

id string | null —

Name: id
Description: The id of the hidden input. When nativeButton is true, the id is applied to the root element instead.
Type: string | null

onCheckedChange function —

Name: onCheckedChange
Description: Called before the checked state changes. Call eventDetails.cancel() to veto it.
Type: (checked: boolean, eventDetails: SwitchRootChangeEventDetails) => void

onclick MouseEventHandler<HTMLElement> | null —

Name: onclick
Description: Runs before the switch's click handler. Call event.preventDefault() to skip it.
Type: MouseEventHandler<HTMLElement> | null

render Snippet<[props: SwitchHostProps, state: SwitchRootState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: SwitchHostProps, state: SwitchRootState, children: Snippet | undefined]>

checked boolean

Name: checked
Description: Whether the switch is currently active.
Type: boolean

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

readOnly boolean

Name: readOnly
Description: Whether the user should be unable to activate or deactivate the switch.
Type: boolean

required boolean

Name: required
Description: Whether the user must activate the switch before submitting a form.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-checked

Present when the switch is checked.

data-unchecked

Present when the switch is not checked.

data-disabled

Present when the switch is disabled.

data-readonly

Present when the switch is readonly.

data-required

Present when the switch is required.

data-valid

Present when the switch is in a valid state (when wrapped in Field.Root).

data-invalid

Present when the switch is in an invalid state (when wrapped in Field.Root).

data-dirty

Present when the switch's value has changed (when wrapped in Field.Root).

data-touched

Present when the switch has been touched (when wrapped in Field.Root).

data-filled

Present when the switch is active (when wrapped in Field.Root).

data-focused

Present when the switch is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-checked`	Present when the switch is checked.
`data-unchecked`	Present when the switch is not checked.
`data-disabled`	Present when the switch is disabled.
`data-readonly`	Present when the switch is readonly.
`data-required`	Present when the switch is required.
`data-valid`	Present when the switch is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the switch is in an invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the switch's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the switch has been touched (when wrapped in Field.Root).
`data-filled`	Present when the switch is active (when wrapped in Field.Root).
`data-focused`	Present when the switch is focused (when wrapped in Field.Root).

Thumb

The movable part of the switch that indicates whether the switch is on or off. Renders a <span>.

render Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: SwitchThumbState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: SwitchThumbState, children: Snippet | undefined]>