---
title: Switch
subtitle: A control that indicates whether a setting is on or off.
description: A high-quality, unstyled React switch component that indicates whether a setting is on or off.
---

> FineSoft Components documentation. Independent Stencil port; not the official Base UI website.
>
> React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable.

# Switch

A high-quality, unstyled React switch component that indicates whether a setting is on or off.

## Demo

### Tailwind

This example shows how to implement the component using Tailwind CSS.

```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactSwitch from './react-switch';
import StencilSwitch from './stencil-switch';

export default function SwitchComparison() {
  return <StencilComparison component="switch" react={<ReactSwitch />} stencil={<StencilSwitch />} />;
}
```

```tsx
/* react-switch.tsx */
import { Switch } from '@base-ui/react/switch';

export default function ExampleSwitch() {
  return (
    <label className="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
      <Switch.Root
        defaultChecked
        className="flex h-5 w-9 shrink-0 border border-neutral-950 bg-white p-0.5 transition-colors duration-150 ease-[ease] dark:border-white dark:bg-neutral-950 data-checked:bg-neutral-950 dark:data-checked:bg-white focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
      >
        <Switch.Thumb className="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>
  );
}
```

```tsx
/* stencil-switch.tsx */
export default function StencilSwitch() {
  return (
    <label className="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
      <fs-switch-root
        default-checked
        className="flex h-5 w-9 shrink-0 border border-neutral-950 bg-white p-0.5 transition-colors duration-150 ease-[ease] dark:border-white dark:bg-neutral-950 data-checked:bg-neutral-950 dark:data-checked:bg-white focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
      >
        <fs-switch-thumb className="[&::part(thumb)]:size-3.5 [&::part(thumb)]:bg-neutral-950 [&::part(thumb)]:transition-[translate,background-color] [&::part(thumb)]:duration-150 [&::part(thumb)]:ease-[ease] data-checked:[&::part(thumb)]:translate-x-4 data-checked:[&::part(thumb)]:bg-white dark:[&::part(thumb)]:bg-white dark:data-checked:[&::part(thumb)]:bg-neutral-950" />
      </fs-switch-root>
      Notifications
    </label>
  );
}
```

### CSS Modules

This example shows how to implement the component using CSS Modules.

```css
/* index.module.css */
.Label {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
  line-height: 1.25rem;
  font-weight: 400;
  color: oklch(14.5% 0 0deg);

  @media (prefers-color-scheme: dark) {
    color: white;
  }
}

.Switch {
  box-sizing: border-box;
  display: flex;
  flex-shrink: 0;
  border: 1px solid oklch(14.5% 0 0deg);
  padding: 0.125rem;
  width: 2.25rem;
  height: 1.25rem;
  background-color: white;
  transition: background-color 150ms ease;

  @media (prefers-color-scheme: dark) {
    border: 1px solid white;
    background-color: oklch(14.5% 0 0deg);
  }

  &[data-checked] {
    background-color: oklch(14.5% 0 0deg);

    @media (prefers-color-scheme: dark) {
      background-color: white;
    }
  }

  &:focus-visible {
    outline: 2px solid oklch(14.5% 0 0deg);
    outline-offset: 2px;

    @media (prefers-color-scheme: dark) {
      outline-color: white;
    }
  }
}

.Thumb {
  width: 0.875rem;
  height: 0.875rem;
  background-color: oklch(14.5% 0 0deg);
  transition:
    translate 150ms ease,
    background-color 150ms ease;

  @media (prefers-color-scheme: dark) {
    background-color: white;
  }

  &[data-checked] {
    translate: 1rem 0;
    background-color: white;

    @media (prefers-color-scheme: dark) {
      background-color: oklch(14.5% 0 0deg);
    }
  }
}
```

```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactSwitch from './react-switch';
import StencilSwitch from './stencil-switch';

export default function SwitchComparison() {
  return <StencilComparison component="switch" react={<ReactSwitch />} stencil={<StencilSwitch />} />;
}
```

```tsx
/* react-switch.tsx */
import { Switch } from '@base-ui/react/switch';
import styles from './index.module.css';

export default function ExampleSwitch() {
  return (
    <label className={styles.Label}>
      <Switch.Root defaultChecked className={styles.Switch}>
        <Switch.Thumb className={styles.Thumb} />
      </Switch.Root>
      Notifications
    </label>
  );
}
```

```tsx
/* stencil-switch.tsx */
export default function StencilSwitch() {
  return (
    <label>
      <fs-switch-root default-checked>
        <fs-switch-thumb />
      </fs-switch-root>
      Notifications
    </label>
  );
}
```

## Stencil boundary

`fs-switch-thumb` exposes its internal movable span through an open ShadowRoot and
`::part(thumb)`. Classes remain on the host; use this part or the
`--fs-switch-thumb-*` theme variables to style the indicator. Checked and disabled
state attributes are available on the host. Inline styles continue to reach the
internal span, while ordinary page selectors cannot style it directly.

`fs-switch-root` retains Light DOM for its native checkbox, switch control, label
association, and form participation. The Base UI theme is built in; select `data-fs-theme="base-ui"` on an ancestor to enable the optional theme.
The Root and authored Thumb content remain accessible to ordinary CSS selectors.

## 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](/react/components/switch.md) and the [forms guide](/react/handbook/forms.md).

## Anatomy

Import the component and assemble its parts:

```jsx title="Anatomy"
import { Switch } from '@base-ui/react/switch';

<Switch.Root>
  <Switch.Thumb />
</Switch.Root>;
```

## Examples

### Labeling a switch

An enclosing `<label>` is the simplest labeling pattern:

```tsx title="Wrapping a label around a switch"
// @highlight
<label>
  <Switch.Root />
  Notifications
  {/* @highlight */}
</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 (`htmlFor`/`id`).

```tsx title="Sibling label pattern with a native button"
<div>
  <label htmlFor="notifications-switch">Notifications</label>
  {/* @highlight-text "nativeButton" "render={<button />}" */}
  <Switch.Root id="notifications-switch" nativeButton render={<button />}>
    <Switch.Thumb />
  </Switch.Root>
</div>
```

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

```tsx title="Render callback"
<Switch.Root
  nativeButton
  // @highlight-start
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Notifications
    </label>
  )}
  {/* @highlight-end */}
/>
```

### Form integration

Use [Field](/react/components/field.md) to handle label associations and form integration:

```tsx title="Using Switch in a form"
<Form>
  {/* @highlight */}
  <Field.Root name="notifications">
    <Field.Label>
      <Switch.Root />
      Notifications
    </Field.Label>
  </Field.Root>
</Form>
```

## API reference

### Root

Represents the switch itself.
Renders a `<span>` element and a hidden `<input>` beside.

**Root Props:**

| Prop            | Type                                                                                      | Default | Description                                                                                                                                                                                   |
| :-------------- | :---------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name            | `string`                                                                                  | -       | Identifies the field when a form is submitted.                                                                                                                                                |
| defaultChecked  | `boolean`                                                                                 | `false` | Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead.                                                                                        |
| checked         | `boolean`                                                                                 | -       | Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead.                                                                              |
| onCheckedChange | `((checked: boolean, eventDetails: Switch.Root.ChangeEventDetails) => void)`              | -       | Event handler called when the switch is activated or deactivated.                                                                                                                             |
| value           | `string`                                                                                  | -       | The value submitted with the form when the switch is on.&#xA;By default, switch submits the "on" value, matching native checkbox behavior.                                                    |
| form            | `string`                                                                                  | -       | Identifies the form that owns the hidden input.&#xA;Useful when the switch is rendered outside the form.                                                                                      |
| nativeButton    | `boolean`                                                                                 | `false` | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `true` if the rendered element is a native button.                          |
| uncheckedValue  | `string`                                                                                  | -       | The value submitted with the form when the switch is off.&#xA;By default, unchecked switches do not submit any value, matching native checkbox behavior.                                      |
| disabled        | `boolean`                                                                                 | `false` | Whether the component should ignore user interaction.                                                                                                                                         |
| readOnly        | `boolean`                                                                                 | `false` | Whether the user should be unable to activate or deactivate the switch.                                                                                                                       |
| required        | `boolean`                                                                                 | `false` | Whether the user must activate the switch before submitting a form.                                                                                                                           |
| inputRef        | `React.Ref<HTMLInputElement>`                                                             | -       | A ref to access the hidden `<input>` element.                                                                                                                                                 |
| id              | `string`                                                                                  | -       | The id of the hidden input element. When `nativeButton` is `true`, the id is applied to the root element.                                                                                     |
| className       | `string \| ((state: Switch.Root.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style           | `React.CSSProperties \| ((state: Switch.Root.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render          | `ReactElement \| ((props: HTMLProps, state: Switch.Root.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Root Data Attributes:**

| Attribute      | Type | 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).             |

### Root.Props

Re-export of [Root](/react/components/switch.md) props.

### Root.State

```typescript
type SwitchRootState = {
  /** Whether the switch is currently active. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to activate or deactivate the switch. */
  readOnly: boolean;
  /** Whether the user must activate the switch before submitting a form. */
  required: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};
```

### Root.ChangeEventReason

```typescript
type SwitchRootChangeEventReason = 'none';
```

### Root.ChangeEventDetails

```typescript
type SwitchRootChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};
```

### Thumb

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

**Thumb Props:**

| Prop      | Type                                                                                       | Default | Description                                                                                                                                                                                   |
| :-------- | :----------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Switch.Thumb.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Switch.Thumb.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: HTMLProps, state: Switch.Thumb.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Thumb Data Attributes:**

| Attribute      | Type | 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.Props

Re-export of [Thumb](/react/components/switch.md) props.

### Thumb.State

```typescript
type SwitchThumbState = {
  /** Whether the switch is currently active. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to activate or deactivate the switch. */
  readOnly: boolean;
  /** Whether the user must activate the switch before submitting a form. */
  required: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};
```

## Export Groups

- `Switch.Root`: `Switch.Root`, `Switch.Root.State`, `Switch.Root.Props`, `Switch.Root.ChangeEventReason`, `Switch.Root.ChangeEventDetails`
- `Switch.Thumb`: `Switch.Thumb`, `Switch.Thumb.Props`, `Switch.Thumb.State`
- `Default`: `SwitchRootState`, `SwitchRootProps`, `SwitchRootChangeEventReason`, `SwitchRootChangeEventDetails`, `SwitchThumbProps`, `SwitchThumbState`

## Canonical Types

Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.

- `Switch.Root.State`: `SwitchRootState`
- `Switch.Root.Props`: `SwitchRootProps`
- `Switch.Root.ChangeEventReason`: `SwitchRootChangeEventReason`
- `Switch.Root.ChangeEventDetails`: `SwitchRootChangeEventDetails`
- `Switch.Thumb.Props`: `SwitchThumbProps`
- `Switch.Thumb.State`: `SwitchThumbState`