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

Use gzip compression

Send outgoing email

User email visibility

Email confirmation

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:

WiFi

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