Component Toggle

A toggle lets users switch between two opposing states, often used to turn a feature on or off.

Get the UI kit

Code

Usage

Example

Show active results

Enable notifications

Props

Attr	Type	Default	Docs
checked	boolean	false	This boolean is used to set the toggle as "checked".
disabled	boolean	false	This boolean is used to disable the toggle.
hide-label	boolean	false	This property will visually hide the label. A label is still required to be provided for screenreader support.
input-aria-label	string	null	This property can be used to set the ARIA label associated with this input (for screen readers).
input-id	string	generateId('som-input')	This property can be used to specifically set an ID to the input field. If an ID is not provided, it will be dynamically generated.
label	string	''	This property can be used to set the inline label.
label-class	string	''	This property is a list of CSS classes that can be used to style the label.
name	string	''	This property is the form element name (used when submitting the form).
size	"lg" \| "sm"	'sm'	This property determines the size of the toggle
value	string	''	This property is the toggle value sent on submit when using it in a form.

Methods

Name	Returns	Docs
setFocus	Promise will resolve after focus.	This public method sets focus to the checkbox element.

Events

Event	Detail	Docs
somBlur	any	This event is emitted when when the toggle loses focus.
somChange	any	This event is emitted when the toggle value changes.
somFocus	any	This event is emitted when when the toggle gets focus.

Slots

Name	Docs
label	Label for the toggle. Alternatively, you can use the label attribute.

Anatomy

The parts of the button, as described in the caption. — Toggle

Toggle switch

Label

Sizes

Large

Small

Labels

Use a label to clearly identify the toggle’s function. Toggles have a default label attribute, but custom labels can be used in some cases, such as user settings. If a toggle is used without a label, additional context like a card boundary or related content should support the toggle’s use.

Avoid writing labels as questions or phrases like “Turn on” or “Turn off” — a toggle inherently represents an on or off state, so restating in the label is unnecessary and may confuse users as to what the toggle actually does.

Proper use of toggle labels, as described in the caption.

The label should clearly indicate the toggle’s function.

Improper use of toggle labels, as described in the caption.

Don’t write labels as questions or use verb phrases that refer to a toggle’s active or inactive state.

How to use

When enabling a feature or functionality, the change should be immediate and obvious, such as toggling between dark and light mode. Toggles should never be used to answer a question or to agree to terms and conditions.

Toggle or checkbox?

When choosing between the two, remember:

Checkboxes allow users to make any number of selections (many, one, or none), while toggles only turn a single binary option on or off.
Unlike checkboxes, toggles reflect an immediate change.
Checkboxes have error states; toggles do not.

A checkbox group used for multiple selection, as described in the caption.

Use a checkbox group when users can select multiple options.

Incorrect use of toggles, as described in the caption.

Each toggle is a unique field and should not be used to collect multiple responses to one prompt.

Behavior

States

Toggles are either in an on or off state. For accessibility purposes, use ARIA labels and roles to describe the toggle and its current state.

Default: The standard state of a toggle.
Hover: When a user’s cursor moves over a toggle without clicking it.
Focus: When a user highlights a toggle via the keyboard.
Disabled: An unavailable action. Ensure that users aren’t confused as to why a toggle is disabled.

Interactions

Mouse

Clicking the toggle will change the state. Users can click on either the toggle or its label.

Keyboard focus

Users can focus on a toggle with the Tab key. The Spacebar will switch the toggle between its on and off states.

Layout

Toggles with related content may be organized together, but avoid arranging them horizontally.

Similar toggle settings grouped together vertically, as described in the caption.

Related toggles should be grouped together vertically.

Toggles incorrectly laid out horizontally, as described in the caption.

Avoid arranging toggles horizontally.

Toggles contained in card components, as described in the caption.

Toggles can be contained within card components.

Get in touch

Do you have an idea, or want to help us improve this page? Reach out to us via email.

DTMB-DG-Support@michigan.gov

Need help? Visit our Support page to learn how to get assistance, troubleshoot issues, and connect with the team.