Log-in required.

You are trying to access the internal Editor Foundations design system.
Sign-in with your Unity Google account to continue, or visit the public site.

Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

Index

1. Basic button and a toolbar button 2a. Grouped independent toggle buttons 2b. Grouped dependent toggle buttons

The Editor includes these variations of buttons:

When to use

A large basic button, dependent toggle buttons, and a toolbar button
  • Buttons are interaction elements that initialize actions, indicate choices, and control interfaces.
    While buttons can have a variety of styles and purposes they all function similarly.
  • Buttons contain text or icons that should always clearly indicate the action they perform
  • Buttons can be clustered together as single buttons or as a button group to create larger design patterns or components

Button variations

Basic button

An illustration of a basic button on the left and a toolbar button on the right
A basic button and a toolbar button
When to use

The basic button initiates a specific action once selected. Once basic button actions are performed their task is complete.

UI Builder button iconUI 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}
APIs in UI Toolkit
Button
Reference for a button.
ToolbarButton
Reference for a button that goes into a window toolbar.
APIs in IMGUI
GUI.Button
Reference for a button.
GUI.Button in toolbars
Use .toolbarbutton style when placing into a window toolbar.
Toggle button (independent)
Independent toggle button
Grouped independent toggle buttons
When to use
  • Independent toggle buttons are used for properties that are not dependent on each other but grouped together thematically (e.g. in TextMeshPro)
  • It is possible to select multiple independent toggle buttons
APIs in IMGUI
Base styles
Group styles
UnityEngine.GUI.Toggle
.minibutton
.Button
.LargeButton
.xxLeft
.xxMid
.xxRight
UnityEngine.GUI.Toggle
Use .toolbarbutton style when placing into a Window Toolbar.
Toggle button (dependent)
Dependent toggle button
Grouped dependent toggle buttons
When to use
  • Dependent toggle buttons are used for properties that are dependent on each other and are tied together functionally (e.g. in Scene Toolbar)
  • It is not possible to select multiple independent toggle buttons
APIs in IMGUI
Base styles
Group styles
UnityEngine.GUILayout
.Toolbar
.minibutton
.Button
.LargeButton
.xxLeft
.xxMid
.xxRight
UnityEngine.GUILayout
.Toolbar
Use .toolbarbutton style when placing into a window toolbar.

Guidance

Choosing buttons

Consider these aspects when deciding whether a button or a toggle button is the right component:

Use a basic button when:
  • Initiating a specific action once selected
  • The action has a non-continuous result (e.g. attaching a collider to a GameObject)
Use a toggle button when:
  • Enabling/disabling a property (e.g. TextMeshPro) or a tool
  • The action causes something to switch between two states (e.g. enabling/disabling lighting in the Scene viewport)

Button order

Button order in the Editor
Button group ordering in the Editor

In the Editor, destructive buttons are aligned on the left, and secondary / primary buttons are aligned on the right hand side of the panel they are displayed in.

Button row span

For most Editor windows, button row spans the full width of the window.
However, consider keeping the buttons aligned to the right corner of the window when:

  • The bottom left corner of the window is busy, and has other elements / actions,
  • When the window will be used wide and users might miss the left hand side.
Button order in dialogs
OS dialogs in macOS 12 / macOS 11 and Win 8 has different button orders

Editor API for dialogs display the native operating system dialog.

Scripting API
EditorUtility.
DisplayDialog
Dialog with two buttons
EditorUtility.
DisplayDialogComplex
Dialog with three buttons
Icon of a red triangle to indicate a message of warning.
Button order in dialogs is dependant on the operating system.
Note that Editor API will automatically display the operating systems default button order.
  1. On macOS 12, button order is; ok / alt / cancel
  2. On macOS 11, button order is; alt / cancel / ok
  3. On Windows, button order is; ok / alt / cancel

Style

Size parameters in IMGUI
Buttons with labels and icons in 3 different sizes in dark theme
Mini, default, and large basic buttons

Buttons come in three sizes in the IMGUI framework:

1. Default button: .Button
2. Large button: .LargeButton
3. Mini button: .minibutton

Grouped buttons in IMGUI
Examples of rounded corners on buttons when used as groups.
When grouping toggle buttons remember to adjust left / right borders and margins

When grouping toggle buttons in the IMGUI framework, use these parameters to adjust left / right borders and margins:

1. Leftmost button: .ButtonLeft
2. Middle button: .ButtonMid
3. Rightmost button: .ButtonRight

Labels
Example of a button containing ellipses that opens a new window with more available choices.
"Export Coordinates..." button opens "Export Coordinates" window
  • Button labels are horizontally and vertically centered
  • When labeling, make sure to highlight the action that the button performs
  • If the button performs an action use an active verb to indicate the user initiates the action
  • If the button is for navigation then indicate the endpoint
  • If the button is to select a tool then use the established icon for its tool type.
    For more information go to Foundations > Iconography
  • For confirmation buttons restate the action being performed or a suggested action relating to the dialog
  • 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.
Label text

Buttons use labels to indicate their function and can be either a basic button or toggle button. Text buttons rely on words to express concepts that cannot be easily conveyed by icons or glyphs in an accessible manner. Buttons have text labels that should clearly and concisely indicate what action they perform.

  • Button labels are limited to a single line of text
  • Use title case for capitalization, making sure text conforms to our writing Style Guide
  • Be concise by avoiding too many words
  • Be clear by using simple, common and specific words; avoid jargon or wording that is vague or obscure

Behavior

Buttons visually communicate their interaction, by changing their state to convey that an action is being performed or is completed.

Because some buttons can relate to an action or process that can be performed multiple times, a button may return to its default state after it is pressed but will still play an animation to convey it has been used.

Formatting

Anatomy and layout

Anatomy
Example of a default button with a label and an icon in dark mode
Default button with a label and an icon

A button can contain the following elements:

1. Label
2. Icon
3. Container

Layout and specs
Margin and padding specs for three button sizes in dark mode
Margin and padding specs for three button sizes

Height and padding specs for three sizes:
1. Mini Button: height is 18px, padding is 2 px 
2. Default Button: height is 20px, padding is 3px
3. Large Button: height is 24px, padding is 5px

Icon of a letter I in a blue circle indicating this is a piece of informational content
Buttons have relative width.
Buttons have relative width based on the layout they are displayed. They can be set to hug their contents or expand to fill the container they are in.

Interaction states

Seven common interaction states for basic buttons in light and dark themes
Interaction states for basic buttons
Seven common interaction states for toggle buttons in light and dark themes
Interaction states for toggle buttons
Default

The default state is the pre-interaction state.

Hover

When the cursor is over the button element.

Active  

When the interaction is occurring or active, such as a menu being open or toggling a property.

Active focused

When the user has highlighted the active button element.

Focused

When the user has highlighted the default button element.

Hover focused

When the cursor is over the focused button element.

Disabled

When the interaction is not available to the user. 

A button's state will vary depending on the state of the action it is performing and whether the action is available or not.

Color

Basic button color variables
A basic button labeled with three color variables in dark theme
1. Button background 2. Button border 3. Button label
1. button-background
--unity-colors-button-background
The background color for a button control
#E4E4E4
#585858
--unity-colors-button-background-focus
The background color for a button control when it has focus
#BEBEBE
#6E6E6E
--unity-colors-button-background-hover
The background color for a button control when the mouse pointer hovers over it
#ECECEC
#676767
--unity-colors-button-background-hover_pressed
The background color for a button control when it is hoverd and pressed
B0D2FC
4F657F
--unity-colors-button-background-pressed
The background color for a button control when it is pressed
#96C3FB
#46607C
2. button-border
--unity-colors-button-border
The border color for a button control
#B2B2B2
#303030
--unity-colors-button-border_accent
The border accent color for a button control
#939393
#242424
--unity-colors-button-border_accent-focus
The border accent color used for a button control when focused
018CFF
7BAEFA
--unity-colors-button-border-pressed
The border color for a button control when it is pressed
#707070
#0D0D0D
3. button-text
--unity-colors-button-text
The text color for a button control
#090909
#EEEEEE
Toggle button color variables
Color variables of a toggle button
Labeled parts of a toggle button showing color variables
1. button-background
--unity-colors-button-background
The background color for a button control
#E4E4E4
#585858
--unity-colors-button-background-focus
The background color for a button control when it has focus
#BEBEBE
#6E6E6E
--unity-colors-button-background-hover
The background color for a button control when the mouse pointer hovers over it
#ECECEC
#676767
--unity-colors-button-background-hover_pressed
The background color for a button control when it is hoverd and pressed
B0D2FC
4F657F
--unity-colors-button-background-pressed
The background color for a button control when it is pressed
#96C3FB
#46607C
2. button-border
--unity-colors-button-border
The border color for a button control
#B2B2B2
#303030
--unity-colors-button-border_accent
The border accent color for a button control
#939393
#242424
--unity-colors-button-border_accent-focus
The border accent color used for a button control when focused
018CFF
7BAEFA
--unity-colors-button-border-pressed
The border color for a button control when it is pressed
#707070
#0D0D0D
3. icon
Primary Icon Color
Icons that don’t require to be color coded uses this color.
#555555
#C4C4C4
Toolbar button color variables
A toggle button labeled with three color variables in dark theme
Color variables of a toolbar button
toolbar container
--unity-colors-toolbar-background
The background color for a toolbar control
#CBCBCB
#3C3C3C
--unity-colors-toolbar-border
The border color for a toolbar control
#999999
#232323
--unity-colors-toolbar_button-border
The border color for a toolbar button control
#999999
#232323
1. toolbar_button-border
--unity-colors-toolbar_button-border
The border color for a toolbar button control
#999999
#232323
2. toolbar_button-background
--unity-colors-toolbar_button-background
The background color for a toolbar button control
#CBCBCB
#3C3C3C
--unity-colors-toolbar_button-background-checked
The background color for a toolbar button control when it is checked
#EFEFEF
#505050
--unity-colors-toolbar_button-background-focus
The background color for a toolbar button control when it has focus
#C1C1C1
#464646
--unity-colors-toolbar_button-background-hover
The background color for a toolbar button control when the mouse pointer hovers over it
#C1C1C1
#464646
3. toolbar_button-text
--unity-colors-tab-text
The text color for an Editor window tab
#090909
#BDBDBD
--unity-colors-toolbar_button-text
The text color for a toolbar button control
#090909
#C4C4C4
--unity-colors-toolbar_button-text-checked
The text color for a toolbar button control when it is checked
#090909
#C4C4C4
--unity-colors-toolbar_button-text-hover
The text color for a toolbar button control
#090909
#BDBDBD

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 button iconUI Bulder toolbar button icon