This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

O3DE UI Toggle Switch Component

Use a toggle switch to enable users to quickly switch between two states with a minimum of effort. The state will be clearly reflected back to them and persisted across sessions.

component toggle switch style

Usage guidelines

Follow these guidelines as you design your UI with toggle switches:

  1. Use the toggle switch when your widget has two binary states, for example: “on/off” or “yes/no”. There should be no ambiguity about potential states.

  2. Always use the active state of the toggle switch for the affirmative state. Affirmative states are those such as “on”, “yes”, or “active”. Consistency here will help customers better understand at a glance the state of a setting.

  3. Even if the active state always means “on”, clearly indicate the consequences of the switch.

Avoid these design choices when using toggle switches:

  • Don’t use when the options presented to the user are not binary. For example, if a mail setting has IMAP and POP as the two mail retrieval options, use a radio group instead. In this example there are actually four states - IMAP on, IMAP off, POP on, and POP off.
  • Don’t use if the state does not persist or get serialized across sessions. For example, don’t use for search filters, since filters are reset each time a user performs a new search.

Basic toggle switch

component toggle switch basic

Toggle switches are implemented using the QCheckBox Qt class. The toggle switch style is then applied using the static function, AzQtComponents::CheckBox::applyToggleSwitchStyle().

Example

#include <AzQtComponents/Components/Widgets/CheckBox.h>
#include <QCheckBox>

// Apply the toggle switch style to a QCheckBox.
QCheckBox* toggleSwitch = new QCheckBox(parent);
AzQtComponents::CheckBox::applyToggleSwitchStyle(toggleSwitch);

// To set the switch to the "on" state:
toggleSwitch->setChecked(true);

// To set the switch to the "off" state:
toggleSwitch->setChecked(false);

// To disable the toggle switch:
toggleSwitch->setEnabled(false);

C++ API reference

For details on the checkbox API used to style a toggle switch, see the following topic in the O3DE UI Extensions C++ API Reference:

Relevant Qt documentation includes the following topics:

For additional information related to the toggle switch component, see the following topics: