Toggle buttons

Summary

A toggle button provides a quick way to see whether a given option is enabled or disabled and to toggle between these states. Place a toggle button to the right of a label, in a table, or below a section describing what is enabled or disabled.

A toggle button should be used if the main intent is to make a binary choice, such as turning something on or off, and the choice is not part of a form.

Status

Examples

Default toggle

Define a basic toggle button.

<aui-toggle id="gzip-compression" label="use gzip compression"></aui-toggle>

The label attribute is required for a screen reader to announce the button. If you want to have an actual visible label, use <aui-label>.

<aui-label for="gzip-compression">Use gzip compression</aui-label>

You can set the default checked and disabled states directly in the HTML, or using Javascript to modify the elements' attributes/properties.

Sometimes you need to provide more information relating to the state of a control. This can be achieved using the tooltip-on and tooltip-off attributes.

Asynchronous toggle

The busy property can be used to handle asynchronous requests. Bind to the change event to trigger an AJAX request and display a spinner when the toggle is pressed:

var form = document.getElementById('wifi-toggle-form');

form.addEventListener('change', function(e) {

    var toggle = document.getElementById('wifi-toggle');

    var isChecked = toggle.checked;     // new value of the toggle

    if (isChecked === false) { // do not call server if unchecked

        console.log("toggle is unchecked");

        return;

    }

    toggle.busy = true;

    $.post('set/my/variable', { value: isChecked })

        .done(function () {

            console.log('success');

        })

        .fail(function () {

            toggle.checked = !isChecked;

            console.error('display an error message');

        })

        .always(function () {

            toggle.busy = false;

        });

});

API Reference

Attributes and properties

Attributes and properties can be set and accessed directly on the aui-toggle element.

var toggle = document.getElementById('my-toggle');

toggle.checked = true;

toggle.disabled = true;

toggle.setAttribute('tooltip-on', 'Enabled');

toggle.tooltipOn = 'Enabled';

toggle.setAttribute('tooltip-off', 'Disabled');

toggle.tooltipOff = 'Disabled';