Implementation references

Scripting API and implementation references.

UI Toolkit

Toggle · UX essentials

Key guidance on using toggle components.

Sliders, numeric fields, and toggles can be interacted with via their label
Blue plus sign icon indicating that clicking on this will expand this content
When to disable controls or hide them altogether
Blue plus sign icon indicating that clicking on this will expand this content

Resources and API documentation


Toggle and toolbar toggle in light and dark themes

Unity Editor contains 2 type of toggles (checkboxes);

  • Toggles are components that allow a user to make binary choices by selecting a box
  • The most common use for a toggle is to select whether or not an option is enabled, visually confirming its status to the user
  • Toggles frequently appear in option windows, as seen in the Inspector and the preferences windows
Icon of a letter I in a blue circle indicating this is a piece of informational content
Toggles and checkboxes
Toggles are alternatively called checkboxes, though that is discouraged in the Editor

Toggle variations

Variations showing a toolbar toggle and a regular toggle which resembles a checkbox.
A comparison of a regular toggle with a a toolbar toggle


A basic toggle showing an unchecked box and text that reads "Toggle Label"
When to use

Toggles are used to allow a user to make binary choices by selecting a box.

UI Builder toggle icon
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}
API in

UI Toolkit

Reference for a toggle
API in


Reference for a toggle
Toolbar toggle
A toolbar toggle
When to use

Toolbar toggles are toggles with button style applied to it and are used inside window toolbars.

UI Builder toolbar toggle icon
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}
API in

UI Toolkit

Reference for a toggle to be placed inside a toolbar
API in


Use .ToolbarToggle style when placing into a Window Toolbar


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
A layer collision matrix showing a set of toggle checkboxes that are checked
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

When To use toggle vs toggle button

A comparison of toggles on the left and toggle buttons on the right
Basic toggles vs toggle buttons

A toggle is a simple on/off boolean control and its generic expression is a checkbox. However in certain conditions the control needs to be placed in a container as a toggle button.

Use a toggle when:

  • Property has a long explanation (eg. Preferences)
  • Enabling the parent property will reveal child properties (eg. The Layer Collision Matrix)

Use a toggle button when:

  • A well-known, identifiable property is enabled / disabled or turned on / off (eg. Edit Collider button). Essentially if it is more clear to the user to turn a button on and off, then use a button. When a button is unclear use a toggle (checkbox)
  • Property is going to appear together with other related properties (eg. TextMeshPro)
  • Property is going to appear in a toolbar. (eg. gizmos)

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 recommendation illustrated by a green checkbox icon
Use direct language in providing options to the user
Don't recommendation illustrated by a red X icon
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
Cursor changing format while moving
Enabling or disabling the physical camera toggle shows or hides its options in the Inspector


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.

Showing a toggle box in its three states of checked, unchecked and indeterminate (or mixed).
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.

  • 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
Showing the location of toggle labels on the right or left of certain components
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


Adjusting with label

Toggles can be enabled / disabled via their handle to give a wider area to interact with the element.

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
A column showing some toggle boxes checked and others unchecked which creates the indeterminate state.
An indeterminate parent toggle.



The parts of a toggle and its label
Default toggle

A toggle can contain and be paired with the following elements:

1. Text label
2. Box
3. Glyph

Interaction states

Showing the visual representation of various interaction states
Interaction states

Toggles can be:

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

Toggle states can be:

  • Default
  • Disabled
  • Hover
  • Focused
  • Pressed


Toggle Color Variables
Toggle in light and dark themes
1. input_field-background
The border color for a helpbox control
2. input_field-border
The text color for a helpbox control
The background color for selected items or selected text
The background color for line items when the mouse pointer hovers over them
rgba(0, 0, 0, 0.0627451)
rgba(256, 256, 256, 0.0627451)
The background color for an item with a line specific background color when the mouse pointer hovers over them
3. icon
Primary Icon Color
Icons that don’t require to be color coded uses this color.

Code samples

UI Toolkit samples

Icon indicating this element is available in UI Builder

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

UI Builder toggle iconUI Builder toolbar toggle icon