Skip to main content
BEEQ Switch component overviewBEEQ 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
  • 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)
Choose bq-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 when users pick one of several named options.

​
Anatomy

BEEQ Switch component anatomyBEEQ 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. Allowed inner-label values: default (default), icon.

​
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. Allowed justify-content values: start (default), end, center, flex-start, flex-end, left, right, space-between, space-around, space-evenly, stretch, normal, inherit, initial.
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.
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.

​
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’tDon’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.
DoUse bq-checkbox with required for consent and bq-radio-group with required for a required choice between named options.
Don’tDon’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

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

​
Rules

​
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

​
Invalid combinations

No invalid prop combinations.

​
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