Implementation references

An overview of implementation references.

Scripting API
EditorWindow.Show
A default window with a tab and dock
.dragtab
This style is used to render the container for window tabs.

Windows · UX essentials

Essential guidance about windows in the Editor.

Adapt your content layout for various window sizes
Blue plus sign icon indicating that clicking on this will expand this content
Dockable windows include tabs and window menus
Blue plus sign icon indicating that clicking on this will expand this content
Dockable windows remain functional through Editor restarts
Blue plus sign icon indicating that clicking on this will expand this content
The interface should support the set min and max sizes of the window
Blue plus sign icon indicating that clicking on this will expand this content

Overview

Editor windows can be displayed in various types

Most Editor controls appear in default windows and can be docked in the main app window. Windows usually perform two principal functions:

  1. To render the interface elements and general content in the provided area and position
  2. To allow the user to generate mouse and keyboard events in the appropriate areas to control the interface

Index

1. Default window  2. Dropdown window  3. Popup window  4. Auxiliary window  5. Modal and utility window

Window types found in the editor:

Choosing windows

Window type and Properties
Scripting reference

A default window with a tab and dock:

  1. Can be docked in tab docks
  2. Can be dragged by the title bar
  3. Can be minimized / maximized
  4. Can be resized by dragging corners
EditorWindow.Show

A window using popup-style framing:

  1. Window position is set by the control that triggers it
  2. Window closes when clicked outside the frame
  3. Does not have a title bar, and cannot be dragged
  4. Cannot be minimized or maximized
  5. Cannot be resized
EditorWindow.ShowAsDropDown

A window using popup-style framing:

  1. Window position can be set manually or determined by the cursor
  2. Window does not close when clicked outside the frame
  3. Does not have a title bar, and cannot be dragged
  4. Cannot be minimized or maximized
  5. Cannot be resized
EditorWindow.ShowPopup

A single instance auxiliary window:

  1. Window can only have one instance
  2. Window position can be set by the control that triggers it
  3. Window closes when clicked outside the frame
  4. Can be dragged by the title bar
  5. Cannot be minimized / maximized
  6. Cannot be resized
EditorWindow.ShowAuxWindow

A persistent modal window:

  1. Always on top and does not allow background interaction
  2. Window position can be set manually or determined by the cursor
  3. Window does not close when clicked outside the frame
  4. Can be dragged with the title bar
  5. Cannot be minimized / maximized
  6. Cannot be resized
EditorWindow.ShowModal

A persistent modal window:

  1. Always on top but allows background interaction
  2. Window position can be set manually or determined by the cursor
  3. Window does not close when clicked outside the frame
  4. Can be dragged with the title bar
  5. Cannot be minimized / maximized
  6. Cannot be resized
EditorWindow.ShowUtility

Dialogs are modal windows rendered by the operating system:

  1. Dialogs are messages that present a short-term task the user must perform to continue the operation
  2. Users will not be able to interact with the Editor until the dialog is closed
EditorUtility.DisplayDialog

Window types

Default window

Illustration of a default window
Scene view displayed in a Editor default window

A default window with a tab and docking area with a window menu.

This window can be docked in tab docks to customize the environment and discreetly stack windows and panels contextually.

When released anywhere on the Editor, it will undock as a modal with a title bar and OS window controls.

  1. Can be docked in tab docks
  2. Can be dragged with the title bar
  3. Can be minimized / maximized
  4. Can be resized by dragging corners
Scripting reference
EditorWindow.Show

Displays any window that has been created

Auxiliary window

An illustration of a basic auxiliary window
Color picker is displayed in an auxiliary window

The single auxiliary window can be re-used by different editor windows at different times. Showing an editor window in the auxiliary window can be useful to avoid clutter of many small windows.

  1. Window can only have one instance
  2. Window position can be set by the control that triggers it
  3. Window closes when clicked outside the frame
  4. Can be dragged with the title bar
  5. Cannot be minimized / maximized
  6. Cannot be resized
Scripting reference
EditorWindow.
ShowAuxWindow

Show the editor window in the auxiliary window.

Utility window

Illustration of a basic utility window
Shortcut manager is displayed in a Utility window

When the utility window loses focus it remains on top of the new active window. This means the utility window is never hidden by the Unity Editor. It will be hidden when the user switches from Unity to another application.

  1. Always on top but allows background interaction
  2. Window position can be set manually or determined by the cursor
  3. Window does not close when clicked outside the frame
  4. Can be dragged with the title bar
  5. Cannot be minimized / maximized
  6. Cannot be resized
Scripting reference
EditorWindow.ShowUtility

Show the EditorWindow as a floating utility window.

Icon of a red triangle to indicate a message of warning.
EditorWindow.GetWindow
You do not need to use EditorWindow.GetWindow before using this function to show the window.

Dialog window

Illustration of a basic dialog window
Dialogs are messages that affect the entirety of the Editor
Plastic CSM requesting user input with a two button macOS 11 dialog

Dialogs are messages that present a short-term task the user must perform to continue the operation. Users won't be able to interact with the Editor until the dialog is closed.

  1. Unity Editor displays the operating system dialog by default
  2. Dialogs should be reserved to be used when a response is required, such as critical messages, interruptive actions or destructive outcomes, eg. saving the project before quitting
  3. Dialogs should have an opt-out from displaying option if they might be shown repeatedly

Window anatomy

Window tab and docking area

Anchored Scene view menu

Default windows in the Editor are instantiated with a window tab, that can contain the name and the icon of the view, and a docking area where multiple tabs can be docked.

  • Tabs organize related windows or content in the Editor by allowing a unique visual location in the interface
  • They function by helping to create a structure for condensing visual elements like windows and controls into a nested and navigable pattern
  • Tabs simplify the visual real estate of the workspace while improving organization and workflows
Script Reference
EditorWindow.ShowTab
Shows a docked Editor window.
.dragtab
This style is used to render the container for tabs
.dragtab-first
This style is used to render a tab without a 1px accent border on its left side when its active (first tab in a series of tabs)
.dragtab-label
This style is used to render the text label for tabs
Anchored Scene view menu
Tab label

Tab labels contain the name of their window. These are meant to indicate the window’s purpose whether it is displayed or grouped behind other tabs. Tab labels should not be displayed vertically.

Icons in tab labels

Only document window tabs, like scene, game, or Inspector should have icons in their tab label. Tool window tabs do not have icons. Tab icons should follow the standard Iconography guidelines. Icons should be simple intelligible glyphs relating to the tab contents. Icons should be placed to the left of the label with a 4px margin.

Tab container

Tab container holds the tab label and icon (if applicable). The container is the area in which a tab’s context menu can be accessed. The tab container also holds the tab’s indicator which shows if the tab is being focused on.

Tab border
Anchored Scene view menu

Tabs have borders based on their order in the docking area. While regular tabs .dragtab have borders on both sides, a tab docked in the first position .dragtab-first only has a right border.

Docking area

The space within a panel that tabs inhabit is the docking area. Although this is technically part of a panel it has an important effect on tab behavior and anatomy; it represents the area in which tabs can inhabit and where other tabs will be grouped when placed in the same panel.

Docking area acts as a container for tab labels, allowing for the placement of tab navigation elements and panel UI. As a result it is persistent even if there are no other tabs in the panel to convey the grouping functionality.

Anchored Scene view menu
Dock anchor menu / window menu

A temporary pop up menu that displays a list of options, triggered by a button or label that invites the user to select preferences.

Use an anchored menu when the items do not need to be visible unless being changed. If you need items to persist and be visible (for example for debugging or settings changes), use a radio button group in the UI or use a default or utility window.

Anchored Scene view menu
Window Menus
Anchored Context Menu's are triggered in docking area. Read more ->

Window frame and body

A window frame and body

A Unity Editor window body displays Editor content and allows user to interact with its contents. When floating, a Unity window is framed by the operating systems window element and a title bar.

It often consists of:

  1. Tab and dock
  2. Toolbars
  3. Panels
  4. Title bar (pictured in macOS 12)
  5. Window frame (pictured in macOS 12)
Icon of a red triangle to indicate a message of warning.
Frame styling is dependant on the operating system.
Window corner radius and box shadows are handled by the native window frame element, and their style is dependant on the operating system.

Setting maximum and minimum sizes

Most editor windows can be resized whether they are docked or floating. maxSize and minSize variables are used to provide the largest and smallest width and height that is supported.

Scripting API
EditorWindow.maxSize
The maximum size of this window when it is floating or modal.
EditorWindow.minSize
The minimum size of this window when it is floating or modal.
Icon of a red triangle to indicate a message of warning.
Docked windows
The maximum size is not used when the window is docked.

Window states

Illustration of the various items involved in window states
Idle, active and always on top windows

A Unity Editor is often in 3 main states;

  1. Idle: A window that is in the background
  2. Active: Currently active window
  3. Always on top: Modal and utility editor windows always remain on top of other windows

Create a custom Editor window

Custom Editor windows allow you to extend Unity by implementing your own editors and workflows.

Follow the guidance below that covers:

  1. Creating an Editor window through code
  2. Reacting to user input
  3. Making the UI resizable
  4. Handling hot-reloading
Icon displaying the Unity logo
Manual: Create a custom Editor window
This guide covers creating an Editor window through code, reacting to user input, making the UI resizable and handling hot-reloading. View guide ->

Window anatomy

Window tab and docking area

Docked windows
The maximum size is not used when the window is docked.

Default windows in the Editor are instantiated with a window tab, that can contain the name and the icon of the view, and a docking area where multiple tabs can be docked.

  • Tabs organize related windows or content in the Editor by allowing a unique visual location in the interface
  • They function by helping to create a structure for condensing visual elements like windows and controls into a nested and navigable pattern
  • Tabs simplify the visual real estate of the workspace while improving organization and workflows
Script Reference
EditorWindow.ShowTab
Shows a docked Editor window.
.dragtab
This style is used to render the container for tabs
.dragtab-first
This style is used to render a tab without a 1px accent border on its left side when its active (first tab in a series of tabs)
.dragtab-label
This style is used to render the text label for tabs
Docked windows
The maximum size is not used when the window is docked.
Tab label

Tab labels contain the name of their window. These are meant to indicate the window’s purpose whether it is displayed or grouped behind other tabs. Tab labels should not be displayed vertically.

Icons in tab labels

Only document window tabs, like scene, game, or Inspector should have icons in their tab label. Tool window tabs do not have icons. Tab icons should follow the standard Iconography guidelines. Icons should be simple intelligible glyphs relating to the tab contents. Icons should be placed to the left of the label with a 4px margin.

Tab container

Tab container holds the tab label and icon (if applicable). The container is the area in which a tab’s context menu can be accessed. The tab container also holds the tab’s indicator which shows if the tab is being focused on.

Tab border
Docked windows
The maximum size is not used when the window is docked.

Tabs have borders based on their order in the docking area. While regular tabs .dragtab have borders on both sides, a tab docked in the first position .dragtab-first only has a right border.

Docked windows
The maximum size is not used when the window is docked.
Docking area

The space within a panel that tabs inhabit is the docking area. Although this is technically part of a panel it has an important effect on tab behavior and anatomy; it represents the area in which tabs can inhabit and where other tabs will be grouped when placed in the same panel.

Docking area acts as a container for tab labels, allowing for the placement of tab navigation elements and panel UI. As a result it is persistent even if there are no other tabs in the panel to convey the grouping functionality.

Docked windows
The maximum size is not used when the window is docked.
Dock anchor menu / window menu

A temporary pop up menu that displays a list of options, triggered by a button or label that invites the user to select preferences.

Use an anchored menu when the items do not need to be visible unless being changed. If you need items to persist and be visible (for example for debugging or settings changes), use a radio button group in the UI or use a default or utility window.

Docked windows
The maximum size is not used when the window is docked.
Window Menus
Anchored Context Menu's are triggered in docking area. Read more ->

Window frame and body

A window frame and body

A Unity Editor window body displays Editor content and allows user to interact with its contents. When floating, a Unity window is framed by the operating systems window element and a title bar.

It often consists of:

  1. Tab and dock
  2. Toolbars
  3. Panels
  4. Title bar (pictured in macOS 12)
  5. Window frame (pictured in macOS 12)
Docked windows
The maximum size is not used when the window is docked.

Setting maximum and minimum sizes

Most editor windows can be resized whether they are docked or floating. maxSize and minSize variables are used to provide the largest and smallest width and height that is supported.

Scripting API
EditorWindow.maxSize
The maximum size of this window when it is floating or modal.
EditorWindow.minSize
The minimum size of this window when it is floating or modal.
Docked windows
The maximum size is not used when the window is docked.