Switch

A switch is an input type that allows users to toggle a value between two states: on or off.

Switches are similar to checkboxes in their semantics and keyboard navigation with the notable difference that checkboxes may optionally allow a third "indeterminate" state, whereas switches do not.

Important: it is critical the label on a switch does not change when its state changes.

Basic example

<button o-component="switch">
    <!-- A label that should be made readable only to screen readers for accessibility purposes -->
    <span>The label</span>
    <!-- The switch's "thumb", only used for styling purposes -->
    <span aria-hidden="true"></span>
</button>

With a custom label

<div o-component="switch-group">
    <span o-part="label">The label</span>

    <button o-component="switch">
        <span>The label</span>
        <span aria-hidden="true"></span>
    </button>
</div>

With a custom description

<div o-component="switch-group">
    <button o-component="switch">...</button>

    <p o-part="description">Lorem ipsum dolor sit amet consectetur adipisicing.</p>
</div>

With a custom passive label

<div o-component="switch-group">
    <span o-part="label" o-data='{ "passive": true }'>The label</span>

    <button o-component="switch">...</button>
</div>

Component API

Anatomy

Name	Type	Parent	Ideal tag	Description
`switch-group`	component	-	-	A parent component grouping "switch", "label" and "description" together .
`switch`	component \| part	- \| switch-group	button	The component.
`label`	part	switch-group	-	The switch's label.
`description`	part	switch-group	-	The switch's description.

Props

Switch

Name	Default	Description
`name`	`el.getAttribute('name') ?? ''`	`string` Serves as the switch's name when used within a from.
`checked`	`el.getAttribute('aria-checked') === 'true'`	`boolean` Determines the checked state of the component.
`required`	`el.getAttribute('aria-required') === 'true'`	`boolean` Determines the required state of the component.
`disabled`	`el.hasAttribute('disabled')`	`boolean` Determines the disabled state of the component.
`labelledBy`	`el.getAttribute('aria-labelledby')`	`string` \| `null` Specifies an element serving as the switch's label.
`describedBy`	`el.getAttribute('aria-describedby')`	`string` \| `null` Specifies an element serving as the switch's description.

Switch label

Name	Default	Description
`passive`	false	`boolean` Determines whether clicking it toggles the switch's state.

Public props

Switch

Name	Description
`$checked: boolean`	Property that allows manuall control of the checked/unchecked state of the component.
`$required: boolean`	Property that allows manuall control of the required state of the component.
`$disabled: boolean`	Property that allows manuall control of the disabled state of the component.
`$check(): void`	Marks the component as being checked.
`$uncheck(): void`	Marks the component as being unchecked.
`$toggle(): void`	Toggles the component's check/uncheck actions.
`$disable(): void`	Marks the component as being disabled.
`$enable(): void`	Unmarks the component as being disabled.
`$require(): void`	Marks the component as being required.
`$optional(): void`	Unmarks the component as being required.