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 that provide an immediate response after any of them are selected.

When not to use

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

Validation

Server side

Server side validation provides a more thorough check on the server once the data has been submitted and helps keep our applications safe.

When using server side validation, display a Critical AlertInline above the form listing all errors with links to each invalid field.

Content

Label

• We recommend keeping labels clear and concise.
• 3.2.2 Labels or Instructions (A): Labels or instructions are provided when content requires user input.

Helper text

• Use helper text when needing to provide the user with extra details about the option(s) you’re asking them to select, ie. Learn more about our pricing.

Error messages

• Error messages need to provide the user with enough context to guide them in resolving the error.
• Keep messages short and to the point.
  • ie. "Select at least one option"
• Avoid over politeness; don’t use “please” or “thank you” in your messages.
• 3.3.1 Error Identification: If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.
• 3.3.3 Error Suggestion (AA): If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.
• 3.3.4 Error Prevention (Legal, Financial, Data) (AA): For Web pages that cause legal commitments or financial transactions for the user to occur, that modify or delete user-controllable data in data storage systems, or that submit user test responses, at least one of the following is true: submissions are reversible, data is checked and the user is provided an opportunity to correct them, a mechanism is available for reviewing, confirming, and correcting the information before finalizing the submission.
• 4.1.4 Status Messages: In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.

Refer to HashiCorp’s Style, Language, and Voice Guidelines for more content tips.

How to use this component

There are different possible ways to use the Form::Toggle component: using the ”base” variant (essentially just the control itself), using the “field” variant (the control plus label, helper text and error), or using the “group” variant (a list of fields with legend, helper text and error).

The "field" and "group" are the most common variants to use because they provide, for free and out of the box, a lot of accessibility-related enhancements. The "base" variant is to be used if and when you need to achieve custom layouts or have special use cases not covered by the other variants.

Form::Toggle::Field

The "field" variant should be used when the user has a single choice to make. If there are multiple related choices, the "group" variant should be used instead.

Basic use

<Hds::Form::Toggle::Field as |F|>
  <F.Label>Enable cost estimation</F.Label>
</Hds::Form::Toggle::Field>

This "field" component 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

Input value

You can provide a value to the input passing to it a @value argument:

<Hds::Form::Toggle::Field @value="enable" as |F|>
  <F.Label>Enable cost estimation</F.Label>
</Hds::Form::Toggle::Field>

Checked

You can set the toggle to “checked” by passing to it the standard HTML checked attribute:

<Hds::Form::Toggle::Field @value="enable" checked as |F|>
  <F.Label>Enable cost estimation</F.Label>
</Hds::Form::Toggle::Field>

Helper text

You can add extra information to the field using HelperText:

<Hds::Form::Toggle::Field as |F|>
  <F.Label>Enable cost estimation</F.Label>
  <F.HelperText>With this option enabled you will receive an approximate cost estimation.</F.HelperText>
</Hds::Form::Toggle::Field>

When HelperText text is added, the component automatically adds an aria-describedby attribute to the input control, associating it with the automatically generated ID of the helper text element.

Extra content in label and helper text

The Label and HelperText contextual components used in the "field" are yielding their content: this means you can pass not just plain text, but also structured content. For example:

<Hds::Form::Toggle::Field as |F|>
  <F.Label>Enable cost estimation <Hds::Badge @size="small" @text="Beta" @color="highlight" /></F.Label>
  <F.HelperText>See <Hds::Link::Inline @href="#">our pricing</Hds::Link::Inline> for more information.</F.HelperText>
</Hds::Form::Toggle::Field>

Validation

The validation of the form fields is entirely delegated to the "consumer" of the HDS components. What we provide is the visual representation of an invalid state of the field at the UI level. When and how to provide this visual feedback to the user is the responsibility of the developer.

To show the user that their input is not valid, you have to provide an error message (using the Error contextual component):

<Hds::Form::Toggle::Field as |F|>
  <F.Label>I approve the changes.</F.Label>
  <F.Error>Error: it is necessary to explicitly approve the changes to continue.</F.Error>
</Hds::Form::Toggle::Field>

Unlike for the TextInput/Textarea/Select, you don’t need to pass a @isInvalid argument to the field, because the toggle control doesn’t have an "invalid" visual state.

Custom control ID

In case it is necessary to have a custom ID for the control, you need to pass a @id argument to the field, instead of the ID automatically generated by the component.

<Hds::Form::Toggle::Field @id="my-control" as |F|>
  <F.Label>Enable cost estimation</F.Label>
  <F.HelperText>With this option enabled you will receive an approximate cost estimation.</F.HelperText>
</Hds::Form::Toggle::Field>

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

Extra "aria-describedby"

If you want to connect one or more extra elements describing the field to the control, it’s possible to provide extra ID values to the aria-describedby attribute of the control, in addition to the ones automatically generated by the component, passing a @extraAriaDescribedBy argument to the "field":

<Hds::Form::Toggle::Field @extraAriaDescribedBy="my-extra-element-ID" as |F|>
  <F.Label>Enable cost estimation</F.Label>
  <F.HelperText>With this option enabled you will receive an approximate cost estimation.</F.HelperText>
</Hds::Form::Toggle::Field>

HTML native attributes

As explained in the Component API section, the input “field” supports the ...attributes spreading of HTML attributes over the <input type="checkbox"> element. This means you can use all the standard HTML attributes of the <input type="checkbox"> element.

<Hds::Form::Toggle::Field name="enable" as |F|>
  <F.Label>Enable cost estimation</F.Label>
</Hds::Form::Toggle::Field>

This can be useful in case you want to add specific native behaviors to the field, that are not exposed directly by the component (eg. providing a name for the control)

Events handling

Thanks to the ...attributes spreading over the <input type="checkbox"> element, you can use as well all the usual Ember techniques for event handling, validation, etc.

<Hds::Form::Toggle::Field {{on "change" this.yourOnChangeFunction}} as |F|>
  <F.Label>Enable cost estimation</F.Label>
</Hds::Form::Toggle::Field>

You can use different events, depending on your context/need (eg. input, change).

Form::Toggle::Group

The "group" variant of the toggle component is to be used when there are multiple related choices to make for the user, or a single one that needs to be presented with an extra "legend". If there is a single choice with no need for an extra "legend", the "field" variant should be used instead.

It’s unlikely that you will ever need to use a "group" of toggle fields (from a design/UX perspective in this case is better to use a group of checkboxes). For this reason we will not explain in detail how to use the "group" variant (apart from the case of a toggle "group" with single choice). Please refer to the documentation for the Form::Toggle::Group documentation for more details, or speak with the Design Systems Team for guidance on what to do in this specific case.

"Group" with single choice

There may be use cases in which you need to create a toggle "group" that contains a single "field" element (eg. for design reasons, to show the "legend" in a similar position for the labels of other controls). In that case is acceptable to have a group with a single "field" element. For example:

<Hds::Form::Toggle::Group as |G|>
  <G.Legend>Visibility</G.Legend>
  <G.Toggle::Field name="private" @id="visibility-private" as |F|>
    <F.Label>Private</F.Label>
    <F.HelperText>Making a box private prevents users from accessing it unless given permission.</F.HelperText>
  </G.Toggle::Field>
</Hds::Form::Toggle::Group>

Form::Toggle::Base

The "base" element is intended only for those rare cases where the "field" or "group" variants can’t be used, and a custom implementation is needed.

When the "base" toggle is used, the developer is completely responsible for the correct implementation of the form control, including its accessibility conformance.

For example, this could be an invocation of the "base" component you would use:

<Hds::Form::Toggle::Base
  name="enable-cost-estimation"
  aria-label="Enable cost estimation"
  @value="enable"
  {{on "change" this.yourOnChangeFunction}}
/>

This "base" component creates the <input type="checkbox"> control with an automatically generated ID attribute.

Component API

The Form::Toggle component has two different variants, with their own APIs:

• Form::Toggle::Base - the "basic" component: just the <input> control
• Form::Toggle::Field - the "field" parent component: the <input> control, with label, helper text and error messaging (in a wrapping container)

Form::Toggle::Base

Form::Toggle::Field

Contextual components

Label, helper text, and error content are passed to the field as yielded components using the Label, HelperText, and Error keys.

Form::Toggle::Group

Contextual components

Legend, group of fields, and error content are passed to the group as yielded components, using the Legend, Toggle::Field, and Error keys.

The group of elements is automatically wrapped in a <fieldset> element.

Anatomy

Base

Group

States

Conformance rating

The Form::Toggle::Base variation of this component is conditionally conformant; that is, it is not conformant until it has an accessible name.

Known Issues

If a link is used within a label, helper text, or error text, it will not be presented as a link to the user with a screen reader; only the text content is read out. It is generally preferable to avoid links within help/error text or labels; however, we understand that this may not be avoidable in some cases. Please use sparingly until a good known alternative approach is determined.

Applicable WCAG Success Criteria

Support

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