Toggle

UI Builder

About UI Builder ->

UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}

When to use

• Toggles should be avoided for processes that involve continuous switching between states or views
• Unlike Radio Buttons which restrict the user to selecting one of a set of options, toggles are used when multiple related options can be enabled at once but are addressed individually
• Toggles can also be used to specify inclusions or exceptions between multiple subjects as seen in the Layer Collision Matrix

Layer Collision Matrix

• Don't use the words "enable"/"use"/"is" in toggle labels; they are implied by the toggle
• Never create a toggle that disables functionality when the toggle is enabled
• Only use toggles for turning things on/off, never for switching between states of this/that.
  Example: "Is orthographic" should be a dropdown with two states "perspective"/"orthographic" rather than a toggle for turning "orthographic" on.
• Don’t use toggles to start actions that make the user wait; use a button instead
• Don’t use toggles for destructive actions such as deleting data or interrupting a process
• Use a toggle button in places where a checkbox is impractical, such as toolbars

Toolbar button "preview" in UI Builder toolbar is checked / Regular toggles in checked, unchecked and indeterminate states

How to use

• Clearly label toggles with their usage explained in plain language. Their purpose must always be discernible from the context provided by their label.

Do

Use direct language in providing options to the user

Don't

Do not use vague language

• Toggles cannot be resized; toggles are consistent in proportion throughout the interface for easy identification
• Toggles can appear alongside other toggles in a matrix, where they are used to indicate whether two different subjects can interact with each other

• Toggles can enable and disable part of the interface elements they correspond to

Enabling or disabling the physical camera toggle shows or hides its options in the Inspector

Style

Toggles are displayed as checkboxes because they are the default display for a boolean (binary) choice between on and off.

A toggle should always show a checkmark for its checked state, a dash for its indeterminate (or mixed) state and be empty for its unchecked state.

Three toggle states: checked, indeterminate (or mixed), and unchecked

A toggle consists of the box, an active glyph, and a label (or two labels where applicable). The “active” glyph indicates whether the choice is true or false, only appearing when the “true” condition is met or enabled.

Toggles should be visually consistent regardless of where they appear. They appear in many interfaces throughout the editor and can even be user-generated in areas of the interface like the Inspector. A consistent visual representation of toggles assures that the functionality works as expected.

Labeling

• A toggle’s label appears to the left of the toggle. The label clearly identifies the toggle’s purpose with precise and direct language
• Toggles often have labels placed nearby to denote their functionality, however their usage is sometimes conveyed contextually as can be seen in the Inspector component toggles; in these cases it is important to consider the placement in the interface of the element to ensure its usage is readable

Property toggles with their labels on their left, and Inspector component toggles with component names and inputs to their right

• For actions that have additional inputs or open windows following the initial choice use an ellipses (...) after the action text. This indicates that the action offers more options or requires additional specification

Behavior

Parent and child toggles

• Checking a parent toggle checks all child toggles
• Unchecking a parent toggle unchecks all child toggles
• Having checked and unchecked child toggles results in an Indeterminate parent toggle

An indeterminate parent toggle.

Anatomy

Default toggle

A toggle can contain and be paired with the following elements:
‍
1. Text label
2. Box
3. Glyph

Interaction states

Interaction states

Toggles can be:

• Checked (selected)
• Unchecked (unselected)
• Mixed (indeterminate)

Toggle states can be:

• Default
• Disabled
• Hover
• Focused
• Pressed

Color

Toggle Color Variables

Toggle in light and dark themes

Editor Color Palette

For general concepts about color use in the Editor go to Fundamentals > Color Palette ->

UI Toolkit samples

Go to Window > UI Toolkit > Samples to view code samples in C# / USS / UXML.