Toggle switch

An alternative presentation for a checkbox, providing a more obvious visual indication of the on/off state.

Turn me on?

Basic usage

Twig

{{
  form.toggle_switch({
    'label': 'Turn me on?',
    'id': 'guid-' ~ random(),
    'name': 'toggle'
  })
}}

HTML

<div class="form__group form__group--toggle">
  <label class="toggle-switch-wrapper-label" for="guid-1181820001">
    <span class="control__label">Turn me on?</span>
    <span class="controls">
      <input id="guid-1181820001" name="toggle" type="checkbox" class="form__control toggle-switch" />
      <span class="toggle-switch-label"></span>
    </span>
  </label>
</div>

Helper options

You can configure this helper using the common helper options. The following options are specific to this helper.

Option	Type	Description
checked	boolean	Whether the input should be checked
indeterminate	boolean	Neither on nor off, shows the toggle in the middle of the options

States

Checked

Checked toggle

Twig

{{
  form.toggle_switch({
    'label': 'Checked toggle',
    'checked': true,
    'id': 'guid-' ~ random(),
    'name': 'toggle-checked'
  })
}}

HTML

<div class="form__group form__group--toggle">
  <label class="toggle-switch-wrapper-label" for="guid-69562041">
    <span class="control__label">Checked toggle</span>
    <span class="controls">
      <input checked id="guid-69562041" name="toggle-checked" type="checkbox" class="form__control toggle-switch" />
      <span class="toggle-switch-label"></span>
    </span>
  </label>
</div>

Indeterminate

info

The indeterminate state can only be set via JavaScript. If you're using toggles in your own components, we'll presume you’re going to manage this.

Twig

{{
  form.toggle_switch({
    'label': 'Indeterminate toggle',
    'id': 'toggle-indeterminate',
    'name': 'toggle-indeterminate'
  })
}}
<!-- example javascript -->
<script type="text/javascript">
  var toggle = document.getElementById("toggle-indeterminate");
  toggle.indeterminate = true;
</script>

HTML

<div class="form__group form__group--toggle">
  <label class="toggle-switch-wrapper-label" for="toggle-indeterminate">
    <span class="control__label">Indeterminate toggle</span>
    <span class="controls">
      <input id="toggle-indeterminate" name="toggle-indeterminate" type="checkbox" class="form__control toggle-switch" />
      <span class="toggle-switch-label"></span>
    </span>
  </label>
</div>
<!-- example javascript -->
<script type="text/javascript">
  var toggle = document.getElementById("toggle-indeterminate");
  toggle.indeterminate = true;
</script>

Best practices

Toggle switches should:

• Be a standalone choice, not grouped together (Use checkboxes or radios instead)
• Clearly indicate the implications of enabling or disabling the setting (e.g. “Disabling this integration will prevent you from taking payments.”)
• Inform the user why a toggle switch is disabled. Provide clear steps explaining how to enable the functionality

Content guidelines

Label

Toggle switch labels should:

• Use active voice/verbs where possible (e.g. Enable, Activate)
• Use as few words as possible to convey their intent

Enable integration

Enable integration

Do keep the label consistent, to indicate state

Enable integration

Disable integration

Don’t change the label to indicate the action that will be performed

Help text

Enable integrationDisabling will prevent customers from making card payments on your site

Do clearly explain the implications of changing this setting

Disable integrationCard payments are enabled

Don’t use help text to indicate state