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:

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

Form::Toggle::Group

Use Form::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 Form::Toggle::Field.

It’s unlikely you’ll need to use Form::Toggle::Group, instead consider using Form::Checkbox::Group.

Group with single choice

There may be use cases in which you need to create a Toggle group that contains a single field element (e.g., to show the Legend in a similar position for other control’s labels).

<Hds::Form::Toggle::Group as |G|>
  <G.Legend>Visibility</G.Legend>
  <G.ToggleField name="demo-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.ToggleField>
</Hds::Form::Toggle::Group>

Form::Toggle::Field

Use Form::Toggle::Field when the user has a single choice to make. If there are multiple related choices, use Form::Toggle::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.

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

Input value

Pass a @value argument.

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

Checked

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

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

Extra content in label and helper text

The Label and HelperText contextual components used in the Field component yield their content. This means you can also pass structured content.

When helper text is added, the component automatically adds an aria-describedby attribute to the fieldset, associating it with the automatically generated ID.

<Hds::Form::Toggle::Field name="demo-cost-estimate" 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>

Required vs. optional

Use the @isRequired and @isOptional arguments 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.