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: general
Web resource key: com.atlassian.auiplugin:aui-toggle
AMD Module key: N/A
Experimental API: 5.9
General API: 7.8
Web Component API: 5.9

Examples

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:

API Reference

Attributes and properties

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

However keep in mind that for IE11 if you render the component and try to access the checked attribute directly after that (in the same event loop) the attribute won't be there yet. Also trying to access internals of the component will cause errors, e.g.

This is caused by the fact that IE11 does not support webcomponents and needs polyfills. In result the web component lifecycle runs a bit later than in other browsers there.

Name Attribute Property Type Description
label required is an attribute is not 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.