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

Scene window toolbar in light and dark themes
  • Toolbars allow grouping of UI control elements for easy access
  • A toolbar can include controls such as buttons, commands, toggles, and dropdowns
  • A toolbar can appear across the top of the application (eg. the play controls) and in individual windows (e.g. the scene view)

Toolbar APIs

1. UI Builder viewport toolbar made with UIT
2. Scene window toolbar in IMGUI

Window toolbar in UI Toolkit

How to use

When working in UIT, use the below API to instantiate the container.
Controls that go inside a toolbar are named accordingly in UIT. (e.g. ToolbarButton)

UI Builder toolbar 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}
UI Toolkit
Toolbar
Reference for a toolbar container
Window toolbar in IMGUI
How to use

When working in IMGUI, use the below API and use the style .Toolbar to instantiate the container. Most Editor controls have a toolbar-styled equivalent. Place controls inside the toolbar container using .Toolbar styling.

IMGUI
UnityEngine.GUILayout:
BeginHorizontal
Toolbar style parameter: .Toolbar

Guidance

When to use

Example of a tab containing a toolbar below the tab label
Some tabs contain toolbars below their labels that affect their contents

Window toolbar sits at the top of a window below the tab label and holds elements that affect or pertain to items in that window. These can include the layout of the window, the creation of objects or elements within the window, or a method of switching between windows and tabs in the same panel.

Using a toolbar when grouping multiple UI control elements improves access to important actions. Frequently used actions for windows or tabs should be added to the toolbar to help streamline the user’s access and enhance their workflow.

How to use

  • Toolbar items should have a clear and logical function
  • Toolbar elements should be related to the window’s function and not the user’s active task
  • Toolbars should be visually consistent with other instances of the same type in the interface
  • Not all primary toolbars have the same location; instead, the primary toolbar is whichever toolbar contains the main actions for the window
  • The type of components in a toolbar vary depending on their location; for example primary toolbars on windows can also contain both tool-selection commands and standard action buttons
  • When there is not enough room to fit all necessary controls into a single toolbar, use multiple toolbars that groups together actions that work on similar areas of the window

Style

Placing elements on left and right edges
As all controls have a left and right border by default, use these left/right styles to remove the respective side border so they can be positioned to the far right or left of the toolbar without creating a double border. (eg. .ToolbarDropdownLeft .ToolbarDropdownRight)

Multiple toolbars
Primary toolbars should always be limited to universal elements. It is recommended to use only one toolbar where possible. However, a second toolbar can be used when there are relevant actions that relate to the window content. 

Do recommendation illustrated by a green checkbox icon
Do
Divide actions into multiple toolbars when needed
 
Don't recommendation illustrated by a red X icon
Don't
Do not include unnecessary actions just to fill empty space in the toolbar

Toolbar element groups

  • Place most frequently used actions on the left of the toolbar with lesser used actions on the right. Users tend to scan the top left portion of the window first
  • Related elements can be placed together within a toolbar to create toolbar element groups. Such groupings structure the toolbar’s contents for easy navigation
  • Divide toolbar element groups by the type of interaction they allow (e.g. tools should be grouped together but toggles should be kept separate); items that are grouped together appear to have related functions
  • Toolbar element groups should be placed with space between others to help separate their function
A toolbar showing various elements grouped for easier navigation
Toolbar element grouping

Formatting

Anatomy and toolbar controls

The window toolbar holds core control elements for key actions related to the window. Toolbar components can range from toggles for switching through different views to pop-ups for controlling what and how information is being displayed in the Editor. 

Window toolbar anatomy
The anatomy of a toolbar with labeled parts
1. Toolbar container: Scene toolbar contains various elements
2. Toolbar controls that are in scene view toolbar
Toolbar controls in IMGUI

Most Editor controls have a toolbar-styled equivalent. When working in IMGUI, place controls inside the toolbar container using .Toolbar styling.  

Layout and focus

Window toolbars should always be located near the edges of tabs or windows. They should be placed above and separate from other contents.

It is recommended to arrange toolbar elements to draw focus to high-traffic actions over low-traffic actions, with high-traffic actions to the left. Arranging content in this way is the most natural for human perception because users tend to scan the user interface from left to right starting from the upper left corner.

A toolbar with a horizontal legend beneath demonstrating high traffic actions on the left and low traffic actions on the right
An example of drawing focus left to right in the  Editor application (main) toolbar; note that high traffic buttons are placed on the left (interaction tools) and low traffic actions on the right side (menus)

Toolbars can be arranged horizontally or vertically and should align along one axis to ease scanning by the user. Exceptions do exist where view controls are placed below tool groups, as in the tile palette window, but only in cases where the grouping is to centralize the elements in the window. This is to ensure readability and to minimize the real estate taken up by the toolbar.

Color

Toolbar container variables
A Game window toolbar with labeled elements showing different colors.
A game window toolbar showing different colors
1
Toolbar Background
--unity-colors-toolbar-background
The background color for a toolbar control
#CBCBCB
#3C3C3C
2
Toolbar Border
--unity-colors-toolbar-border
The border color for a toolbar control
#999999
#232323
3
Toolbar Button Background
--unity-colors-toolbar_button-background
The background color for a toolbar button control
#CBCBCB
#3C3C3C
Toolbar Button Background Checked
--unity-colors-toolbar_button-background-checked
The background color for a toolbar button control when it is checked
#EFEFEF
#505050
Toolbar Button Background Focus
--unity-colors-toolbar_button-background-focus
The background color for a toolbar button control when it has focus
#C1C1C1
#464646
Toolbar Button Background Hover
--unity-colors-toolbar_button-background-hover
The background color for a toolbar button control when the mouse pointer hovers over it
#C1C1C1
#464646
4
Toolbar Button Border
--unity-colors-toolbar_button-border
The border color for a toolbar button control
#999999
#232323

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 toolbar icon