Toggle Button

Ask a question Design guidelines

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

API status: experimental
Included in AUI core? Not in core You must explicitly require the web resource key.
Web resource key: com.atlassian.auiplugin:aui-toggle
AMD Module key: N/A
Experimental since: 5.9

Default toggle

Define a basic toggle button.

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>.

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:

Attributes and properties

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

Name Attribute Property Type Description
label required is an attribute is a property String

Text used by screen readers when announcing the toggle button (required for accessibility).

checked is an attribute is a property Boolean If set, the toggle will be set to the 'on' state.
disabled is an attribute is a property Boolean If set, the user will not be able to interact with the toggle.
form is an attribute is a read-only property String

The form element that the toggle button is associated with. The attribute is the id of the form element, while the read-only property returns the element.

HTML5 attribute. Not supported in IE10 or older.

name is an attribute is a property String The name of the toggle button element, used to reference the element in JavaScript or form data.
value is an attribute is a property String The value associated with the toggle button element (sent on form submission).
busy is not an attribute is a property Boolean

Sets the toggle to a busy state, displaying the busy spinner.

tooltip-on is an attribute is a property String

Sets the tooltip text that is shown when the toggle is set to the ‘on’ state.
The default value is On.

tooltip-off is an attribute is a property String

Sets the tooltip text that is shown when the toggle is set to the ‘off’ state.
The default value is Off.