Switch

A toggle control enabling users to switch between "on" and "off" states.

	<script lang="ts">
  import { Label, Switch } from "bits-ui";
</script>
 
<div class="flex items-center space-x-3">
  <Switch.Root
    id="dnd"
    name="hello"
    class="peer inline-flex h-[36px] min-h-[36px] w-[60px] shrink-0 cursor-pointer items-center rounded-full px-[3px] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-foreground data-[state=unchecked]:bg-dark-10 data-[state=unchecked]:shadow-mini-inset dark:data-[state=checked]:bg-foreground"
  >
    <Switch.Thumb
      class="pointer-events-none block size-[30px] shrink-0 rounded-full bg-background transition-transform data-[state=checked]:translate-x-6 data-[state=unchecked]:translate-x-0 data-[state=unchecked]:shadow-mini dark:border dark:border-background/30 dark:bg-foreground dark:shadow-popover dark:data-[state=unchecked]:border"
    />
  </Switch.Root>
  <Label.Root for="dnd" class="text-sm font-medium">Do not disturb</Label.Root>
</div>

Overview

The Switch component provides an intuitive and accessible toggle control, allowing users to switch between two states, typically "on" and "off". This component is commonly used for enabling or disabling features, toggling settings, or representing boolean values in forms. The Switch offers a more visual and interactive alternative to traditional checkboxes for binary choices.

Key Features

  • Accessibility: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support.
  • State Management: Internally manages the on/off state, with options for controlled and uncontrolled usage.
  • Stylable: Data attributes allow for smooth transitions between states and custom styles.
  • HTML Forms: Can render a hidden input element for form submissions.

Architecture

The Switch component is composed of two main parts:

  • Root: The main container component that manages the state and behavior of the switch.
  • Thumb: The "movable" part of the switch that indicates the current state.

Structure

Here's an overview of how the Switch component is structured in code:

	<script lang="ts">
	import { Switch } from "bits-ui";
</script>
 
<Switch.Root>
	<Switch.Thumb />
</Switch.Root>

Reusable Components

It's recommended to use the Switch primitives to create your own custom switch component that can be used throughout your application.

In the example below, we're using the Checkbox and Label components to create a custom switch component.

MySwitch.svelte
	<script lang="ts">
	import { Switch, Label, useId, type WithoutChildrenOrChild } from "bits-ui";
 
	let {
		id = useId(),
		checked = $bindable(false),
		ref = $bindable(null),
		...restProps
	}: WithoutChildrenOrChild<Switch.RootProps> & {
		labelText: string;
	} = $props();
</script>
 
<Switch.Root bind:checked bind:ref {id} {...restProps}>
	<Switch.Thumb />
</Switch.Root>
<Label.Root for={id}>{labelText}</Label.Root>

You can then use the MySwitch component in your application like so:

	<script lang="ts">
	import MySwitch from "$lib/components/MySwitch.svelte";
 
	let notifications = $state(true);
</script>
 
<MySwitch bind:checked={notifications} labelText="Enable notifications" />

Managing Checked State

Bits UI offers several approaches to manage and synchronize the Switch's checked state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:checked directive. This method automatically keeps your local state in sync with the switch's internal state.

	<script lang="ts">
	import { Switch } from "bits-ui";
	let myChecked = $state(true);
</script>
 
<button onclick={() => (myChecked = false)}> uncheck </button>
 
<Switch.Root bind:checked={myChecked} />

Key Benefits

  • Simplifies state management
  • Automatically updates myChecked when the switch changes (e.g., via clicking on the switch)
  • Allows external control (e.g., checking via a separate button/programmatically)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onCheckedChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Switch } from "bits-ui";
	let myChecked = $state(false);
</script>
 
<Switch.Root
	checked={myChecked}
	onCheckedChange={(checked) => {
		myChecked = checked;
		// additional logic here.
	}}
/>

Use Cases

  • Implementing custom behaviors on checked/unchecked
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the switch's checked state, use the controlledChecked prop. This approach requires you to manually manage the checked state, giving you full control over when and how the component responds to change events.

To implement controlled state:

  1. Set the controlledChecked prop to true on the Switch.Root component.
  2. Provide a checked prop to Switch.Root, which should be a variable holding the current state.
  3. Implement an onCheckedChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { Switch } from "bits-ui";
	let myChecked = $state(false);
</script>
 
<Switch.Root controlledChecked checked={myChecked} onCheckedChange={(c) => (myChecked = c)}>
	<!-- ... -->
</Switch.Root>

When to Use

  • Implementing complex checked/unchecked logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Disabled State

You can disable the switch by setting the disabled prop to true.

	<Switch.Root disabled>
	<!-- ...-->
</Switch.Root>

HTML Forms

If you pass the name prop to Switch.Root, a hidden input element will be rendered to submit the value of the switch to a form.

By default, the input will be submitted with the default checkbox value of 'on' if the switch is checked.

	<Switch.Root name="dnd">
	<!-- ... -->
</Switch.Root>

Custom Input Value

If you'd prefer to submit a different value, you can use the value prop to set the value of the hidden input.

For example, if you wanted to submit a string value, you could do the following:

	<Switch.Root name="dnd" value="hello">
	<!-- ... -->
	<Switch.Thumb />
</Switch.Root>

Required

If you want to make the switch required, you can use the required prop.

	<Switch.Root required>
	<!-- ... -->
</Switch.Root>

This will apply the required attribute to the hidden input element, ensuring that proper form submission is enforced.

API Reference

Switch.Root

The root switch component used to set and manage the state of the switch.

Property Type Description
checked $bindable
boolean

Whether or not the switch is checked.

Default: false
onCheckedChange
function

A callback function called when the checked state of the switch changes.

Default: undefined
controlledChecked
boolean

Whether or not the checked state is controlled or not. If true, the component will not update the checked state internally, instead it will call onCheckedChange when it would have otherwise, and it is up to you to update the checked prop that is passed to the component.

Default: false
disabled
boolean

Whether or not the switch is disabled.

Default: false
name
string

The name of the hidden input element, used to identify the input in form submissions.

Default: undefined
required
boolean

Whether or not the switch is required to be checked.

Default: false
value
string

The value of the hidden input element to be used in form submissions when the switch is checked.

Default: undefined
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
''

The switch's checked state.

data-checked
''

Present when the switch is checked.

data-disabled
''

Present when the switch is disabled.

data-switch-root
''

Present on the root element.

Switch.Thumb

The thumb on the switch used to indicate the switch's state.

Property Type Description
ref $bindable
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
''

The switch's checked state.

data-checked
''

Present when the switch is checked.

data-switch-thumb
''

Present on the thumb element.