`<bmx-switch>`

An on/off control for a setting that takes effect immediately, with the same chrome as the rest of the form family around it.

18 properties · 4 events · 5 methods · 9 parts

Example

Show markup

<div class="row">
  <bmx-switch label="Dark mode" description="Takes effect immediately — which is what makes it a switch rather than a checkbox."></bmx-switch>
</div>
<div class="row">
  <bmx-switch label="Two-factor authentication" checked="true" checked-text="On" unchecked-text="Off"></bmx-switch>
</div>
<div class="row">
  <bmx-switch label="Small" size="sm"></bmx-switch>
  <bmx-switch label="Large" size="lg" tone="success" checked="true"></bmx-switch>
  <bmx-switch label="Disabled" disabled="true"></bmx-switch>
</div>

WHEN TO USE THIS RATHER THAN A CHECKBOX

The two are not interchangeable, and the difference is not decorative. A checkbox states an intention that a form will act on when it is submitted; a switch performs an action the moment it moves. "Email me about offers" on a sign-up form is a checkbox. "Dark mode" in a settings panel is a switch.

That is also why this component has no indeterminate. A checkbox can legitimately be undecided; a light is either on or it is off, and a switch showing a third state is describing something a switch cannot do.

HOW IT IS BUILT

A real <input type="checkbox"> carrying role="switch", which is the pairing ARIA in HTML permits and the one that keeps everything the platform gives a checkbox - Space to toggle, form participation, constraint validation, a focus ring the browser can find - while changing what a screen reader announces from "checkbox, ticked" to "switch, on".

As with bmx-checkbox, the input fills a 24-pixel target invisibly and the track is drawn beside it, so WCAG 2.2 SC 2.5.8 is met whether or not the caption is visible. The reasoning is written out in bmx-checkbox.css.

Properties

Property	Attribute	Type	Default	Description
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the switch once it has rendered.
`checked`	`checked`	`boolean`	`false`	Whether the switch is on. Two-way: the component writes back to it.
`checkedText`	`checked-text`	`string`	—	Text shown beside the track while the switch is on - "On", typically. Decoration, not the accessible state: `role="switch"` already announces on and off, so this text is hidden from assistive technology rather than read out a second time in whatever words the consumer chose. Named for `checked` rather than for "on" because Stencil rejects a property whose name begins with `on` followed by a capital - it reads it as an event handler somebody has mistakenly declared as a property, which is a good rule that happens to catch `onText`.
`description`	`description`	`string`	—	Help text below the row.
`disabled`	`disabled`	`boolean`	`false`	Disable the switch.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container, pushing the caption away from the track.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the caption visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The caption. Required unless the `label` slot is used.
`labelPlacement`	`label-placement`	`BmxSwitchLabelPlacement`	`'end'`	Which side of the track the caption sits on. Logical, so RTL flips it.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`required`	`required`	`boolean`	`false`	Require the switch to be on before its form will submit.
`size`	`size`	`BmxSize`	`'md'`	Size step. Scales the track, the caption and the supporting text together.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role for the on state and the focus ring.
`uncheckedText`	`unchecked-text`	`string`	—	Text shown beside the track while the switch is off - "Off", typically.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string`	`'on'`	What the form receives when the switch is on.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the switch loses focus.
`bmxChange`	`BmxSwitchChangeDetail`	Fired when the switch moves, by user action or by `toggle()`.
`bmxFocus`	`void`	Fired when the switch gains focus.
`bmxValidityChange`	`BmxSwitchValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the switch passed, without revealing anything.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the switch.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the switch if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the switch.
`toggle`	`toggle() => Promise<void>`	Move the switch, as a click would. Does nothing while it is disabled.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich caption content, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The row holding the track, the state text and the caption.
`box`	The wrapper around the control and the drawn track.
`control`	The native checkbox carrying `role="switch"`.
`description`	The help text.
`error`	The error message.
`label`	The caption.
`state`	The on/off text, when `checked-text` or `unchecked-text` is set.
`thumb`	The part of the track that moves.
`track`	The drawn track.

CSS custom properties

Property	Description
`--bmx-switch-background`	The track's background when off.
`--bmx-switch-checked-background`	The track's background when on. Defaults to the tone's solid colour.
`--bmx-switch-duration`	How long the thumb takes to travel. Zero under reduced motion.
`--bmx-switch-font-size`	The caption's font size.
`--bmx-switch-gap`	Space between the track, the state text and the caption.
`--bmx-switch-height`	The track's height. The clickable target stays at least 24px regardless.
`--bmx-switch-padding`	Space between the thumb and the inside of the track.
`--bmx-switch-support-font-size`	Font size of the description and error message.
`--bmx-switch-thumb-color`	The thumb's colour.
`--bmx-switch-thumb-shadow`	The thumb's shadow, which is what lifts it off the track.
`--bmx-switch-width`	The track's width.