Toggle

A toggle is a form element that allows users to select between two mutually exclusive states.

Usage

When to use

• To allow users to turn on and off two mutually exclusive options providing an immediate response.

When not to use

• When users could check and uncheck an option, consider Checkbox.
• When users need to select more than one option from a list, consider Checkbox.
• When only one choice can be selected, consider Radio buttons.

Layout

We recommend using vertical Toggle groups, especially with short option lists.

Error validation

For error validation recommendations, refer to the Form patterns documentation.

How to use this component

There are two ways to use the Toggle component, which is based on the HTML checkbox input. Both are the <i80-toggle> element:

• the base control: an <i80-toggle> with your own <input> written inside it
• the field: an <i80-toggle> with a label attribute — the <input> control, with label, helper text, and error messaging (in a wrapping container)

The group

Use a group — <i80-toggle-group> — when there are multiple related options to choose from, or a single one that needs to be presented with an extra legend. If there’s a single choice and no need for an extra legend, use a single field.

It’s unlikely you’ll need to use a Toggle group, instead consider using a Checkbox group.

The field

Use a single field when the user has a single choice to make. If there are multiple related choices, use a group.

The basic invocation creates:

• a <label> element with a for attribute automatically associated with the input ID attribute.
• a <input type="checkbox"> control with an automatically generated ID attribute.

<i80-toggle label="Enable cost estimation" name="demo-cost-estimate"></i80-toggle>

Input value

Pass a value.

<i80-toggle label="Enable cost estimation" name="demo-cost-estimate" value="enable"></i80-toggle>

Checked

Pass the standard HTML checked attribute to set the Toggle to “checked”.

<i80-toggle label="Enable cost estimation" name="demo-cost-estimate" value="enable" checked></i80-toggle>

Required vs. optional

Use the required and optional attributes to add a visual indication next to the legend text that the field is "required" or "optional".

Note: While the Toggle component is already normally required by the nature of its use for on/off selection, there may be rare instances in which a Toggle is turned off by default but requires the user to interact with it before submitting a form. For example, for accepting terms and conditions.

<i80-toggle label="Private" name="demo-private" required></i80-toggle>
<i80-toggle label="Private" name="demo-private" optional></i80-toggle>

Validation

To indicate a field is invalid, provide an error message: the error attribute.

Unlike the Text Input, Textarea and Select components, you don’t need to mark the control invalid as well — the error attribute is enough — because the Toggle doesn’t have an “invalid” visual state.

<i80-toggle label="I approve the changes." name="demo-approve-change" error="Error: it is necessary to explicitly approve the changes to continue."></i80-toggle>

Custom control ID

If needing a custom ID for the control instead of the one automatically generated by the component, write the <input> yourself inside the element with that id.

In this case all the internal references (id/for/aria-describedby) between the different parts of the field are still automatically generated and will use the custom ID provided.

<i80-toggle label="Enable cost estimation" helper-text="With this option enabled you will receive an approximate cost estimation.">
  <input type="checkbox" name="demo-cost-estimate" id="my-control">
</i80-toggle>

HTML native attributes

The element passes name, value, checked, required, disabled and readonly on to the <input type="checkbox"> it creates. For any other native behavior, write the <input> yourself inside the element and it is kept as it is, with all its attributes.

<i80-toggle label="Enable cost estimation" name="demo-cost-estimate"></i80-toggle>

The base control

The base control is intended for rare cases where the field or the group can’t be used and a custom implementation is needed. Most of the details for the field also apply to it, but see the Component API for more details.

Write the <input type="checkbox"> inside the element with its own aria-label.

<i80-toggle>
  <input type="checkbox" name="demo-cost-estimate" value="enable" aria-label="Enable cost estimation">
</i80-toggle>

Attributes

<i80-toggle> renders this component. Everything it understands:

The tag keeps any native element you write inside it, so a server-rendered form, link or button works as it is. See Web Components for loading i80.js and the reference for these examples running.

Anatomy

A single toggle

A group of toggles

States

For general content recommendations, refer to the Primitives documentation.

Conformance rating

A toggle without a label

A toggle is not conformant until it has an accessible name. Give <i80-toggle> a label — a real <label for> pointing at the control — or, if the name is already somewhere else on the page, an aria-label.

The control itself is an <input type="checkbox"> with role="switch", and the element keeps its aria-checked in step, so a screen reader announces it as on or off rather than as checked or unchecked. Several toggles under one name belong in an <i80-toggle-group>, which renders a <fieldset> with the legend attribute as its <legend>.

Known issues

The helper text and the error are announced through aria-describedby, and a screen reader reads only their text. A link inside them is not announced as a link, so a keyboard user has no way to reach it from the announcement. Put links in the surrounding page content rather than in a label, helper text or error message.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

0.1.0

Første i80-version (fork af upstream, se core/UPSTREAM.md).