Design

Toggles are used when the user needs to choose between two mutually-exclusive options; and that choice has a high impact, risk or importance.

Toggles can be set to disabled, but they cannot be set to an unselected or pre-selection state: one of the two options is always selected. Toggles may use either icons or text to represent each option.

Particularly high-impact options should use the Caution Toggle. The key example of this is when the toggle is to enable or disable a user's access, or to enable or disable an entire data room:

Use Caution Toggles extremely rarely. Save them only for the highest-impact interactions in the application.

Design Rules

  • Less-important options should simply use a standard form checkbox or radio set.
  • If the interaction requires an unselected or pre-selection state, use standard form radio buttons.
  • If both states can be selected independently, use standard form radio buttons.
  • If more than two options are required, use standard form radio buttons.
  • If the control is not directly saving a result, in most cases use Buttons or Pressed Buttons instead. For example, if the control is filtering content for the rest of the page but not saving the result of that action, use pressed buttons. Or if the control is applying a "select all" or "select none", standard buttons may be more appropriate.
  • A Toggle may be used as an indirect control if it is controlling a full set of Toggles in close proximit - eg. in the head of a table, above a column full of Toggles.

Code

It's important to note that in the DOM, each Toggle is actually a radio button with two options; with a label for each radio button. Events and state affecting the entire control are set on the wrapper element.

Code Rules

  • Toggle options must always have human-readable label text whether visibly revealed or 'hidden' by an icon.
  • When the states are generic (on/off, enabled/disabled), Toggles should be enclosed in a fieldset and legend to provide context. This is usually handled within the Forms component.
  • Regardless of the visible labels, to provide a usable reference Toggle has the concept of one state being 'on' and the other being 'off'.
  • To set the on or off state you need to add the checked attribute to the radio input element for that state.
  • Ensure the label FOR attribute matches the ID attribute in the input.
  • When using a Toggle inside a Form, use a Multi Input Group - see Forms page for details.
Example Element Code
Icon Toggle set to off state. 

                                                                                          <div class="ace-toggle ace-toggle-icon" id="enabledOff">
                                                                                            <input checked="checked" id="enabledOffoff" type="radio" name="enabledOff" value="Off">
                                                                                            <label for="enabledOffoff"><span class="ace-icon ace-icon-control-off"></span><span class="ace-text">Off</span>
                                                                                            </label>
                                                                                            <input id="enabledOffon" type="radio" name="enabledOff" value="On">
                                                                                            <label for="enabledOffon"><span class="ace-icon ace-icon-control-on"></span><span class="ace-text">On</span>
                                                                                            </label>
                                                                                          </div>

                                                                                      <% ace.Toggle(Array(_
                                                                                        "onstatetext", "on",_
                                                                                        "offstatetext", "off",_
                                                                                        "name", "enabledOnASP",_
                                                                                        "checkedstate", "on"_
                                                                                      )) %>
Caution Toggle set to off state. 

                                                                                          <div class="ace-toggle ace-toggle-icon ace-toggle-caution" id="enabledOffCaution">
                                                                                            <input checked="checked" id="enabledOffCautionoff" type="radio" name="enabledOffCaution" value="Off">
                                                                                            <label for="enabledOffCautionoff"><span class="ace-icon ace-icon-control-off"></span><span class="ace-text">Off</span>
                                                                                            </label>
                                                                                            <input id="enabledOffCautionon" type="radio" name="enabledOffCaution" value="On">
                                                                                            <label for="enabledOffCautionon"><span class="ace-icon ace-icon-control-on"></span><span class="ace-text">On</span>
                                                                                            </label>
                                                                                          </div>

Full template support to follow. In the short term, set customClass to ace-toggle-caution
Text Toggle set to off state. 

                                                                                          <div class="ace-toggle ace-toggle-text" id="TextOff">
                                                                                            <input checked="checked" id="TextOffoff" type="radio" name="TextOff" value="Off">
                                                                                            <label for="TextOffoff"><span class="ace-text">Off</span>
                                                                                            </label>
                                                                                            <input id="TextOffon" type="radio" name="TextOff" value="On">
                                                                                            <label for="TextOffon"><span class="ace-text">On</span>
                                                                                            </label>
                                                                                          </div>

                                                                                      <% ace.Toggle(Array(_
                                                                                        "type", "text",_
                                                                                        "onstatetext", "on",_
                                                                                        "offstatetext", "off",_
                                                                                        "name", "TextOffASP",_
                                                                                        "checkedstate", "off"_
                                                                                      )) %>
Toggle set to on state. 

                                                                                          <div class="ace-toggle ace-toggle-icon" id="enabledOn">
                                                                                            <input id="enabledOnoff" type="radio" name="enabledOn" value="Off">
                                                                                            <label for="enabledOnoff"><span class="ace-icon ace-icon-control-off"></span><span class="ace-text">Off</span>
                                                                                            </label>
                                                                                            <input checked="checked" id="enabledOnon" type="radio" name="enabledOn" value="On">
                                                                                            <label for="enabledOnon"><span class="ace-icon ace-icon-control-on"></span><span class="ace-text">On</span>
                                                                                            </label>
                                                                                          </div>

                                                                                      <% ace.Toggle(Array(_
                                                                                        "onstatetext", "on",_
                                                                                        "offstatetext", "off",_
                                                                                        "name", "enabledOffASP",_
                                                                                        "checkedstate", "off"_
                                                                                      )) %>
Toggles can be set to Disabled in both on and off state.

Toggles will appear disabled when set to aria-disabled="true"; or they appear within disabled fieldsets. Note this is style only and you must also set each input to disabled="disabled" to actually prevent activation.


                                                                                          <div class="ace-toggle ace-toggle-icon" id="disabledIconOff" aria-disabled="true">
                                                                                            <input disabled="disabled" checked="checked" id="disabledIconOffoff" type="radio" name="disabledIconOff" value="Off">
                                                                                            <label for="disabledIconOffoff"><span class="ace-icon ace-icon-control-off"></span><span class="ace-text">Off</span>
                                                                                            </label>
                                                                                            <input disabled="disabled" id="disabledIconOffon" type="radio" name="disabledIconOff" value="On">
                                                                                            <label for="disabledIconOffon"><span class="ace-icon ace-icon-control-on"></span><span class="ace-text">On</span>
                                                                                            </label>
                                                                                          </div>

                                                                                      <% ace.Toggle(Array(_
                                                                                        "type", "icon",_
                                                                                        "onstatetext", "on",_
                                                                                        "offstatetext", "off",_
                                                                                        "name", "disabledIconOffASP",_
                                                                                        "checkedstate", "off",_
                                                                                        "disabled", "true"_
                                                                                      )) %>

Javascript

Events

Event Description Example
change When a Toggle''s state is changed, a change event is triggered on the radio button set within the toggle control. Remember to listen for events on the radio buttons and not the Toggle''s wrapper element. 

                                                                    $('#toggleID input[type=radio]').on('change', function(){ 
                                                                      //Do something 
                                                                    });

Optional Methods

Function Arguments Description Example
init elementSelector Initialise the specified Toggle(s). Relevant events will be bound to toggle. 
ACE.ToggleControl.init('.ace-toggle');
destroy elementSelector Removes all event bindings from the specified Toggle(s). 
ACE.ToggleControl.destroy('.ace-toggle');