> ## Documentation Index
> Fetch the complete documentation index at: https://www.beeq.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch

> Switches are digital on/off toggles that give users immediate, visible control over a single binary setting without requiring form submission.

![BEEQ Switch component overview](https://mintlify.s3.us-west-1.amazonaws.com/beeq/components/images/switch/switch-overview-light.svg)

Switch component overview

A switch is a binary control that immediately toggles a setting on or off. Unlike checkboxes, a switch should trigger an instant change — no submit button needed. Use it for toggling preferences, enabling features, or activating modes where the result is visible right away.

> [!NOTE]
>
> Use a [Checkbox](https://www.beeq.design/components/checkbox.md) when the choice is part of a form that requires explicit submission, or when multiple items can be selected at once. Use a Switch when the action takes immediate effect.

## When to use

> [card]
>
> Use a switch when
>
> * Toggling a single setting that takes effect immediately
> * The on/off state directly controls a feature, mode, or preference
> * The action does not require a separate confirmation or form submission
> * You need a compact, recognizable binary control

> [card]
>
> Do not use a switch when
>
> * The setting only takes effect after the user clicks a Save or Submit button
> * Multiple related options need to be selected together (use checkboxes)
> * The action is irreversible and needs a confirmation step
> * The label text does not clearly describe the result of toggling
> * The user must turn it on to continue, such as accepting terms (use `bq-checkbox`)
> * The user must pick one of several named options (use `bq-radio-group`)

> [!TIP]
>
> Choose [`bq-checkbox`](https://www.beeq.design/components/checkbox) instead of `bq-switch` when the choice is submitted with a form, acknowledges terms, or lets users select several items, and [`bq-radio-group`](https://www.beeq.design/components/radio) when users pick one of several named options.

## Anatomy

![BEEQ Switch component anatomy](https://mintlify.s3.us-west-1.amazonaws.com/beeq/components/images/switch/switch-anatomy-light.svg)

Switch component anatomy

The switch is composed of a toggle control (track + dot) and an optional label. When `inner-label` is set to `icon`, check and X marks appear inside the track to reinforce the on/off state.

| Part | Element | Description |
| - | - | - |
| **1** | Switch toggle | The rounded track and sliding dot that act as the toggle surface |
| **2** | Icon | Optional icon inside the track to reinforce the on/off state (icon mode only) |
| **3** | Label | Optional text describing what the switch controls |

## Design guidelines

### States

A switch has four interactive states: **default** (off), **checked** (on), **focused**, and **disabled**. Hover adds a subtle background when `background-on-hover` is enabled. The disabled state prevents all interaction and dims the control to signal it is unavailable.

> [!NOTE]
>
> Always pair a switch with a visible text label unless the context makes the purpose unmistakably clear (for example, a dark-mode toggle adjacent to sun and moon icons). Unlabeled switches are inaccessible by default.

### Inner label

**1. Default (no inner label)**

The track contains only the sliding dot. This is the most compact presentation and works well in dense settings panels.

**2. Icon inner label**

Set `inner-label="icon"` to show a check icon when ON and an X icon when OFF inside the track. This adds a secondary visual reinforcement of the state without relying on color alone.

**3. Custom icon slots**

Replace the default icons by providing content to the `icon-on` and `icon-off` named slots alongside `inner-label="icon"`. Use this for domain-specific icons such as a moon/sun pair for a dark-mode toggle.

### Label position

By default, the label appears to the right of the control. Set `reverse-order` to move it to the left — useful in right-to-left layouts or when a consistent label-first alignment is required across a settings list.

## Usage

### Default

The default switch provides a basic on/off toggle functionality, allowing users to control a binary state effortlessly.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch>Toggle me!</bq-switch>
```

```tsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch>Toggle me!</BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `<bq-switch>Toggle me!</bq-switch>`,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch>Toggle me!</BqSwitch>
</template>
```

> [!TIP]
>
> You don't need to specify any additional property or attribute that uses its default value.

### Checked

Use the `checked` attribute to set the initial state of the toggle as ON. This is ideal when you want the switch to start in an activated position.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch checked>Toggle me!</bq-switch>
```

```tsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch checked>Toggle me!</BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `<bq-switch checked>Toggle me!</bq-switch>`,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch checked>Toggle me!</BqSwitch>
</template>
```

## Options

### Disabled

The disabled switch prevents user interaction, making it visually clear that the toggle functionality is not currently available or applicable. Use the `disabled` attribute to enable this type of switch.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch disabled>Toggle me!</bq-switch>
```

```tsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch disabled>Toggle me!</BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `<bq-switch disabled>Toggle me!</bq-switch>`,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch disabled>Toggle me!</BqSwitch>
</template>
```

### With inner label

Enhance user understanding by incorporating an inner label that provides context about the current state of the switch. Use the `inner-label="icon"` attribute to activate this variant.

**Allowed `inner-label` values:** `default` (default), `icon`.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch inner-label="icon">Toggle me!</bq-switch>
```

```tsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch innerLabel="icon">Toggle me!</BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `<bq-switch inner-label="icon">Toggle me!</bq-switch>`,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch innerLabel="icon">Toggle me!</BqSwitch>
</template>
```

### Custom icons

Use the `icon-on` and `icon-off` slots to replace the default check and X marks. The slots render inside the track when `inner-label="icon"` is enabled.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch checked inner-label="icon" name="theme-mode">
  <bq-icon slot="icon-on" name="moon" size="16"></bq-icon>
  <bq-icon slot="icon-off" name="sun" size="16"></bq-icon>
  Dark mode
</bq-switch>
```

```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch checked innerLabel="icon" name="theme-mode">
    <BqIcon slot="icon-on" name="moon" size="16" />
    <BqIcon slot="icon-off" name="sun" size="16" />
    Dark mode
  </BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon, BqSwitch],
  template: `
    <bq-switch checked inner-label="icon" name="theme-mode">
      <bq-icon slot="icon-on" name="moon" size="16"></bq-icon>
      <bq-icon slot="icon-off" name="sun" size="16"></bq-icon>
      Dark mode
    </bq-switch>
  `,
})
export class ThemeSwitchComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon, BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch checked innerLabel="icon" name="theme-mode">
    <BqIcon slot="icon-on" name="moon" size="16" />
    <BqIcon slot="icon-off" name="sun" size="16" />
    Dark mode
  </BqSwitch>
</template>
```

> [!TIP]
>
> Mind the icon size. It should be consistent with the switch size.

### Reverse order

The reverse order switch alters the visual arrangement, placing the toggle on the opposite side for a customizable user interface by adding the `reverse-order` attribute.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch reverse-order>Toggle me!</bq-switch>
```

```tsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <BqSwitch reverseOrder>Toggle me!</BqSwitch>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `<bq-switch reverse-order>Toggle me!</bq-switch>`,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch reverseOrder>Toggle me!</BqSwitch>
</template>
```

### Full width

Use `full-width` with `reverse-order` and `justify-content="space-between"` to build standard settings-list rows where the label is on the left and the toggle sits flush to the right edge.

**Allowed `justify-content` values:** `start` (default), `end`, `center`, `flex-start`, `flex-end`, `left`, `right`, `space-between`, `space-around`, `space-evenly`, `stretch`, `normal`, `inherit`, `initial`.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-switch
  background-on-hover
  full-width
  justify-content="space-between"
  name="bq-switch"
  reverse-order
  value="show-app-list"
>
  Show app list in menu
</bq-switch>
<bq-switch
  background-on-hover
  checked
  full-width
  justify-content="space-between"
  name="bq-switch"
  reverse-order
  value="show-recently-apps"
>
  Show recently added apps
</bq-switch>
<bq-switch
  background-on-hover
  disabled
  full-width
  justify-content="space-between"
  name="bq-switch"
  reverse-order
  value="show-used-apps"
>
  Show most used apps
</bq-switch>
<bq-switch
  background-on-hover
  checked
  full-width
  justify-content="space-between"
  name="bq-switch"
  reverse-order
  value="show-app-notifications"
>
  Show app notifications
</bq-switch>
```

```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSwitch } from "@beeq/react";

export default () => (
  <>
    <BqSwitch
      backgroundOnHover
      fullWidth
      justifyContent="space-between"
      name="bq-switch"
      reverseOrder
      value="show-app-list"
    >
      Show app list in menu
    </BqSwitch>
    <BqSwitch
      backgroundOnHover
      checked
      fullWidth
      justifyContent="space-between"
      name="bq-switch"
      reverseOrder
      value="show-recently-apps"
    >
      Show recently added apps
    </BqSwitch>
    <BqSwitch
      backgroundOnHover
      disabled
      fullWidth
      justifyContent="space-between"
      name="bq-switch"
      reverseOrder
      value="show-used-apps"
    >
      Show most used apps
    </BqSwitch>
    <BqSwitch
      backgroundOnHover
      checked
      fullWidth
      justifyContent="space-between"
      name="bq-switch"
      reverseOrder
      value="show-app-notifications"
    >
      Show app notifications
    </BqSwitch>
  </>
);
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqSwitch],
  template: `
    <bq-switch
      background-on-hover
      full-width
      justify-content="space-between"
      name="bq-switch"
      reverse-order
      value="show-app-list"
    >
      Show app list in menu
    </bq-switch>
    <bq-switch
      background-on-hover
      checked
      full-width
      justify-content="space-between"
      name="bq-switch"
      reverse-order
      value="show-recently-apps"
    >
      Show recently added apps
    </bq-switch>
    <bq-switch
      background-on-hover
      disabled
      full-width
      justify-content="space-between"
      name="bq-switch"
      reverse-order
      value="show-used-apps"
    >
      Show most used apps
    </bq-switch>
    <bq-switch
      background-on-hover
      checked
      full-width
      justify-content="space-between"
      name="bq-switch"
      reverse-order
      value="show-app-notifications"
    >
      Show app notifications
    </bq-switch>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqSwitch } from "@beeq/vue";
</script>

<template>
  <BqSwitch
    backgroundOnHover
    fullWidth
    justifyContent="space-between"
    name="bq-switch"
    reverseOrder
    value="show-app-list"
  >
    Show app list in menu
  </BqSwitch>
  <BqSwitch
    backgroundOnHover
    checked
    fullWidth
    justifyContent="space-between"
    name="bq-switch"
    reverseOrder
    value="show-recently-apps"
  >
    Show recently added apps
  </BqSwitch>
  <BqSwitch
    backgroundOnHover
    disabled
    fullWidth
    justifyContent="space-between"
    name="bq-switch"
    reverseOrder
    value="show-used-apps"
  >
    Show most used apps
  </BqSwitch>
  <BqSwitch
    backgroundOnHover
    checked
    fullWidth
    justifyContent="space-between"
    name="bq-switch"
    reverseOrder
    value="show-app-notifications"
  >
    Show app notifications
  </BqSwitch>
</template>
```

> [!TIP]
>
> Use a combination of `full-width`, `justify-content`, and `reverse-order`. Be creative!

### Form integration

`bq-switch` participates in native forms through `ElementInternals`. A checked switch submits `"on"` for its `name`; an unchecked switch is omitted from `FormData`.

A required switch blocks form submission until it is ON, and `form-validation-message` sets the text of the native validation bubble. Set `required` only when the form cannot continue unless the switch is ON.

> [!TIP]
>
> Consent belongs on `bq-checkbox` with `required`. A required choice between named options belongs on `bq-radio-group` with `required`. A required switch should always carry `form-validation-message`.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<form id="switch-form">
  <bq-switch
    checked
    form-validation-message="Enable release alerts to continue"
    inner-label="icon"
    name="releaseAlerts"
    required
  >
    Release alerts
  </bq-switch>
  <bq-button appearance="secondary" type="reset">Reset</bq-button>
  <bq-button type="submit">Save</bq-button>
  <pre id="switch-output">{}</pre>
</form>

<script>
  const form = document.querySelector('#switch-form');
  const output = document.querySelector('#switch-output');

  form.addEventListener('submit', (event) => {
    event.preventDefault();
    output.textContent = JSON.stringify(Object.fromEntries(new FormData(form).entries()), null, 2);
  });

  form.addEventListener('reset', () => {
    requestAnimationFrame(() => {
      output.textContent = '{}';
    });
  });
</script>
```

```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useState } from "react";
import { BqButton, BqSwitch } from "@beeq/react";

export default function SwitchForm() {
  const [data, setData] = useState("{}");

  return (
    <form
      onReset={() => setData("{}")}
      onSubmit={(event) => {
        event.preventDefault();
        setData(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget).entries()), null, 2));
      }}
    >
      <BqSwitch
        checked
        formValidationMessage="Enable release alerts to continue"
        innerLabel="icon"
        name="releaseAlerts"
        required
      >
        Release alerts
      </BqSwitch>
      <BqButton appearance="secondary" type="reset">Reset</BqButton>
      <BqButton type="submit">Save</BqButton>
      <pre>{data}</pre>
    </form>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqSwitch } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqSwitch],
  template: `
    <form (reset)="data = '{}'" (submit)="handleSubmit($event)">
      <bq-switch
        checked
        form-validation-message="Enable release alerts to continue"
        inner-label="icon"
        name="releaseAlerts"
        required
      >
        Release alerts
      </bq-switch>
      <bq-button appearance="secondary" type="reset">Reset</bq-button>
      <bq-button type="submit">Save</bq-button>
      <pre>{{ data }}</pre>
    </form>
  `,
})
export class SwitchFormComponent {
  data = "{}";

  handleSubmit(event: SubmitEvent): void {
    event.preventDefault();
    this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
  }
}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqSwitch } from "@beeq/vue";

const data = ref("{}");

function handleSubmit(event: Event) {
  data.value = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
}
</script>

<template>
  <form @reset="data = '{}'" @submit.prevent="handleSubmit">
    <BqSwitch
      checked
      formValidationMessage="Enable release alerts to continue"
      innerLabel="icon"
      name="releaseAlerts"
      required
    >
      Release alerts
    </BqSwitch>
    <BqButton appearance="secondary" type="reset">Reset</BqButton>
    <BqButton type="submit">Save</BqButton>
    <pre>{{ data }}</pre>
  </form>
</template>
```

## Best practices

> [card]
>
> Do
>
> Use concise, present-tense labels that clearly describe the result of the switch being on. "Enable notifications" or "Dark mode" communicate the outcome at a glance.

> [card]
>
> Don't
>
> Use vague labels like "Toggle" or "On/Off". Users should not need to think about what the switch controls — the label must describe the setting itself.

> [card]
>
> Do
>
> Apply the switch's effect immediately without requiring a submit action. Use this pattern for preferences that take effect in real time — dark mode, notifications, or feature flags.

> [card]
>
> Don't
>
> Use a switch when the change only takes effect after the user clicks a Save button. If the state is not immediately applied, use a checkbox inside a form instead.

> [card]
>
> Do
>
> Use `inner-label="icon"` to supplement the color change with a shape cue (check / X). This improves the control for users with color vision deficiencies who cannot rely on brand color alone.

> [card]
>
> Don't
>
> Rely solely on the track color to communicate the ON state. Always ensure that at least one additional cue — dot position or icon — distinguishes the two states.

> [card]
>
> Do
>
> Place the label directly adjacent to the switch and keep the pairing stable across the list. Consistent label position helps users scan a settings panel without searching for the control.

> [card]
>
> Don't
>
> Don't change the label text based on state (for example, "Enabled" when on and "Disabled" when off). The label should always describe the setting; the control itself communicates the current state.

> [card]
>
> Do
>
> Use `bq-checkbox` with `required` for consent and `bq-radio-group` with `required` for a required choice between named options.

> [card]
>
> Don't
>
> Don't use a required switch as a consent or choose-one control. A switch that must be ON is a checkbox in disguise, and users read an OFF switch as a valid answer.

## Accessibility

`bq-switch` renders a native `<input type="checkbox" role="switch">` inside its shadow DOM, which ensures that assistive technologies correctly announce the control as a switch with an on/off state.

### Keyboard interaction

| Key | Context | Action |
| - | - | - |
| `Tab` | Any | Moves focus to the next focusable element, including the switch |
| `Shift` + `Tab` | Any | Moves focus to the previous focusable element, including the switch |
| `Space` | Switch focused | Toggles the switch on or off |

The native `<input type="checkbox" role="switch">` handles these keys. A disabled switch ignores `Space`.

### Rules

| Rule | Strength | Verified by |
| - | - | - |
| Provide a visible text label in the default slot | MUST | manual: inspect the visible label beside the switch |
| Set `name` so the switch submits with the form | MUST | automated: [`bq-switch.e2e.tsx`](https://github.com/Endava/BEEQ/blob/main/packages/beeq/src/components/switch/__tests__/bq-switch.e2e.tsx) checks `FormData` |
| Turn a required switch ON before submitting the form | MUST | automated: [`bq-switch.e2e.tsx`](https://github.com/Endava/BEEQ/blob/main/packages/beeq/src/components/switch/__tests__/bq-switch.e2e.tsx) checks `form.checkValidity()` |
| Set `form-validation-message` on a required switch | SHOULD | manual: inspect the required-switch validation message |
| Tell users before submit that a required switch has to be ON | MUST | manual: read instructions before submitting a required switch |
| Provide at least one cue besides track color for the ON state | MUST | manual: check the ON state without relying on track color |
| Explain why a switch is disabled in the surrounding text | SHOULD | manual: inspect nearby text for disabled switches |
| Call `vFocus()`, `vBlur()` and `vClick()` instead of `focus()`, `blur()` and `click()` on the host | SHOULD | manual: inspect host method calls in the consumer code |

### Developer responsibilities

* You must provide a visible text label via the default slot. The switch derives its accessible name from the `name` prop via `aria-label` on the native `<input>`; the visible slot text is not automatically wired to the control. To make the visible label the accessible name, you should use `aria-labelledby` on the host element pointing to the associated label element.
* You must set the `name` attribute (required) to participate in form submissions and to give the control a machine-readable identifier.
* When the switch is `disabled`, it is excluded from the tab order and does not respond to keyboard or pointer events. You should communicate the reason for disabling through surrounding text.
* You must tell users before submit that a required switch has to be ON. The validation bubble only appears after a failed submit.
* The `bqChange` event is cancelable. Calling `event.preventDefault()` inside a `bqChange` handler prevents the switch from updating its visual state, which is useful when you need to confirm a change before applying it.
* You should use `vFocus()`, `vBlur()`, and `vClick()` instead of the global `element.focus()`, `element.blur()`, and `element.click()` to interact with the native input correctly across Shadow DOM boundaries.

## API reference

### Properties

| Property | Attribute | Description | Type | Default |
| - | - | - | - | - |
| `backgroundOnHover` | `background-on-hover` | If `true`, a background is shown on hover | `boolean` | `false` |
| `checked` | `checked` | If `true`, the switch starts in the ON state | `boolean` | `false` |
| `disabled` | `disabled` | If `true`, the switch is disabled and non-interactive | `boolean` | `false` |
| `formValidationMessage` | `form-validation-message` | Custom native form validation message | `string` | — |
| `fullWidth` | `full-width` | If `true`, the switch expands to fill its container | `boolean` | `false` |
| `innerLabel` | `inner-label` | How to display the on/off marks inside the control | `'default' \| 'icon'` | `'default'` |
| `justifyContent` | `justify-content` | Space distribution between the control and label; accepts any `justify-content` value | `'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'left' \| 'right' \| 'space-between' \| 'space-around' \| 'space-evenly' \| 'stretch' \| 'normal' \| 'inherit' \| 'initial'` | `'start'` |
| `name` | `name` | Form control name; submitted as part of a name/value pair | `string` | **required** |
| `required` | `required` | If `true`, the switch must be ON before the form can be submitted. For consent use `bq-checkbox`; for a required choice use `bq-radio-group`. | `boolean` | `false` |
| `reverseOrder` | `reverse-order` | If `true`, the label appears before the control | `boolean` | `false` |
| `value` | `value` | Sets the underlying `<input>` value attribute. Note: the form submission value is the fixed string `'on'` when checked (via ElementInternals), regardless of this prop | `string` | — |

### Invalid combinations

No invalid prop combinations.

### Methods

| Method | Description | Signature |
| - | - | - |
| `vBlur()` | Removes focus from the native `<input>` element | `Promise<void>` |
| `vClick()` | Simulates a click on the native `<input>` element | `Promise<void>` |
| `vFocus()` | Sets focus on the native `<input>` element | `Promise<void>` |

### Events

| Event | Description | Type |
| - | - | - |
| `bqBlur` | Emitted when the switch loses focus | `CustomEvent<HTMLBqSwitchElement>` |
| `bqChange` | Emitted when the switch state changes; cancelable via `event.preventDefault()` | `CustomEvent<{ checked: boolean }>` |
| `bqFocus` | Emitted when the switch gains focus | `CustomEvent<HTMLBqSwitchElement>` |

### Slots

| Slot | Description |
| - | - |
| *(default)* | The label text displayed next to the control |
| `icon-on` | Custom icon shown inside the track when the switch is ON (requires `inner-label="icon"`) |
| `icon-off` | Custom icon shown inside the track when the switch is OFF (requires `inner-label="icon"`) |

### Shadow parts

| Part | Description |
| - | - |
| `base` | The `<label>` root container element |
| `control` | The `<div>` element that forms the toggle track |
| `dot` | The `<div>` element that acts as the sliding indicator dot |
| `icon-on` | The `<bq-icon>` element used as the ON mark (icon mode only) |
| `icon-off` | The `<bq-icon>` element used as the OFF mark (icon mode only) |
| `label` | The `<span>` element that holds the label text |

### CSS custom properties

**CSS variables**

| Variable | Description | Default |
| - | - | - |
| `--bq-switch--height` | Height of the switch track | `24px` |
| `--bq-switch--width` | Width of the switch track | `44px` |
| `--bq-switch--dot-size` | Diameter of the sliding dot | `calc(var(--bq-switch--height) - (var(--bq-spacing-xs2) * 2))` |
| `--bq-switch--dot-color` | Color of the sliding dot | `var(--bq-ui--primary)` |
| `--bq-switch--dot-color-checked` | Color of the sliding dot when checked | `var(--bq-text--on-brand)` |
| `--bq-switch--icon-color` | Color of the inner icon when unchecked | `var(--bq-icon--inverse)` |
| `--bq-switch--icon-color-checked` | Color of the inner icon when checked | `var(--bq-text--on-brand)` |
| `--bq-switch--label-text-color` | Label text color | `var(--bq-text--primary)` |
| `--bq-switch--track-color` | Track color | `var(--bq-ui--tertiary)` |
| `--bq-switch--track-color-checked` | Track color when checked | `var(--bq-ui--brand)` |
| `--bq-switch--justify-content` | Space distribution between the control and label | `start` |

> [!TIP]
>
> Learn more about [styling with shadow parts](https://www.beeq.design/guides/styles.md) and [CSS custom properties](https://www.beeq.design/theming/global-css-variables.md).

## Resources

> [card] [Interactive playground](https://storybook.beeq.design/?path=/story/components-switch--default)
>
> Explore switch variants and states in Storybook

> [card] [Source code](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components/switch)
>
> View the component source on GitHub


## Related topics

- [Themes & Modes](https://www.beeq.design/theming/themes-and-modes.md)
- [Changelog](https://www.beeq.design/releases/changelog.md)
- [Tab](https://www.beeq.design/components/tab.md)
- [Table](https://www.beeq.design/components/table.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.