Skip to main content
BEEQ Switch component overview

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.
Use a Checkbox 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

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

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

​
Anatomy

BEEQ Switch component anatomy

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.

​
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.
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.
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.

​
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.

​
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.

​
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.
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.

​
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.
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. Use required only when the form cannot continue unless the switch is ON.

​
Best practices

DoUse 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.

Don’tUse 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.

DoApply 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.

Don’tUse 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.

DoUse 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.

Don’tRely 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.

DoPlace 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.

Don’tChange 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.

​
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

​
Developer responsibilities

  • Always 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. If you want the visible label to serve as the accessible name, use aria-labelledby on the host element pointing to the associated label element.
  • Use 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 will not respond to keyboard or pointer events. Make sure the reason for disabling is communicated through surrounding text.
  • 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.
  • 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

​
Methods

​
Events

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore switch variants and states in Storybook

Source code

View the component source on GitHub