Implementation references

UI Toolkit
USS Classes
The default style class that defines 1 px top and bottom margins and flex behavior in property fields.
Style class used to align a BaseField element automatically with other fields in an Inspector window.
The default style class that defines outer horizontal margins of an Inspector window: 18 px left and 4 px right


Contents shown in the Unity Editor such as property controls can be placed across the Editor windows depending on their context, asset type, and what type of object or property they effect.

Different contexts require different tools and windows to be surfaced, and the location where the content is placed plays a crucial role in authoring workflows.

These contents can also be grouped in multiple ways such as: read-only content groups; property fields; or controls that contextually belong together.

Content Grouping

Since the Unity Editor has a high density interface with many elements shown in the viewport at a time, it is important to group elements logically without creating visual clutter.

In order to help users parse content easily, elements on the interface can be grouped using containers, vertical spacing, altered background colors and with headers or foldouts.

Inspector spacing

Inspector Window inner paddings
  • Inspector windows effectively have 18 px left and 4 px right, and 8 px top and bottom inner paddings.
  • In the UITK framework, USS class .unity-inspector-element–uie adds the inner paddings to the Inspector window itself.
  • In the UITK framework, USS class .unity-base-field__inspector-field adds inner paddings to the Property field itself.
Cursor changing format while moving
Inner padding of the Inspector window.
Margins between fields
  • Single property fields in the Inspector are vertically separated by 2 px by default.
  • In the UITK framework, .unity-base-field USS class adds 1 px top and bottom margins to the property container (effectively parsing fields by 2 px).
Cursor changing format while moving
Individual property fields with 1 px top and bottom margins
  • Grouped property fields are vertically separated by 8 px by default. This can be achieved by increasing the last property field’s bottom margin to 7 px, making the effective vertical space 8 px in total.
  • Alternately, if a property field's margin values cannot be changed, a 7 px spacer can be added after the field to create the needed 8 px spacing in total.
Cursor changing format while moving
Grouped property fields have additional 7 px bottom margin
Rely on vertical spacing when grouping

The best way to parse element groups is to simply add extra vertical spacing between them. Placing element groups in containers when it is not necessary adds visual clutter and unnecessary indentation.

Tabs used to group location of search query
Tabs used to group location of search query
Tabs used to group location of search query
Tabs used to group location of search query

Container usage

Group property fields inside a container to hint at additional interactivity between these fields,
such as reordering or adding removing elements.

Throughout the Unity Editor, elements displayed in containers hint at interactivity, such as regular controls like buttons or dropdowns, or larger patterns such as reorderable lists, tiles, draggable elements or any grouped elements that have interactions between them.

Therefore do not use containers to group elements together if these elements do not share any interaction as a group.

Note that adding your content in containers will add a horizontal indentation to the group.

Cursor changing format while moving
Reorderable lists can have multiple lines of elements, and they are represented in a container because a user can drag these elements to reorder
In panels you can place a piece of content in a container if it is significantly different from the content surrounding it, such as messages, warnings or temporary processes.

In certain cases, placing your content in a container can help users parse this content from the rest of the interface.

Temporary actions such as loading or progress content can also be displayed in a container to signify its non-persistent state.

Cursor changing format while moving
Helpboxes and message banners that appear in the interface are example uses of a container, designating this content as significantly different from the rest of the elements on the panel

Altering background

Similar to the use of containers, altering the background color of an element, or element group should be reserved to hint interactivity, or to separate this group entirely from the rest of the interface.

Inspector and component headers use a lighter background than the rest of the Inspector to indicate their higher level in a hierarchy.
Tabs used to group location of search query

Inspector headers display the selected scene object’s global properties, such as its name, icon, and tag and layer settings. It is the highest hierarchy in the Inspector window, followed by the component headers and property controls.

The background of these interfaces are varied with lighter backgrounds to showing higher levels of hierarchy in the Inspector window.

Note: Component headers have a lighter background color both on idle and hover states, even though their interactivity is clear from having the carat icon. This is done to treat component headers as a separate higher element that groups everything under them.

Editor interface background colors get darker as content gets more detailed, going from lighter at Selected Object and Component headers, to darker for component controls and sub controls.

Cursor changing format while moving
Interface backgrounds get darker as they get lower in the hierarchy
Similar to component headers, regular Foldout controls hint at their interaction by changing background color on hover, in addition to their carat (chevron) icon.

Note that the Foldout control does not have an altered background color when idle. It hints at the interaction by having the expand/collapse carat icon and lighter background color on hover.

Cursor changing format while moving
Interaction states of a Foldout control

Headers vs foldouts

The most common way of grouping elements is to use a Label header or a Foldout control.

Use a foldout for grouping together a larger number of fields that should have the ability to be hidden or revealed.

When grouping a larger number of property fields, using a foldout can help users keep their interface uncluttered and minimalized by collapsing the group of fields when they are not needed.

Cursor changing format while moving
Grouped and single property fields in the Inspector
Cursor changing format while moving
Use of headers and foldouts in grouping multiple levels of controls

Do use headers for content that should stay visible and do not require the expand / collapse function.

Do not place foldouts / headers and their content in a container, unless the container has other functionality like reordering or adding / removing fields.

Do not add high traffic controls under foldouts in order to keep them visible at all times.

Use a label header to group together a small number of fields that should always be visible.

When grouping property fields that range between 2 and 5, adding a top header to this group can help users understand the grouping context.

Do use headers for content that should stay visible, and don't require expand / collapse function.

Avoid using bold labels when grouping

It is generally not recommended to bold a label, whether as a header or a foldout, unless it signifies something specific.

In the context of solely grouping fields, placing them under a header or foldout with left indentation, already gives the visual hint that this is a group, bolding a label will give an impression of higher significance in the interface.

Do reserve the use of bold labels for component headers and other instances where a label needs higher visibility than the rest of the labels in the same interface.

Segmenting content in tabs

Tabs help organize and group content across segmented panels in the same viewport using a horizontal tabbed control that switches between the panels.

Tabs used to group location of search query
  • Tabs are used to navigate between different panels of content that should be shown within the same context / viewport (eg. staying in place while alternating between panels),
  • Tab contentContainer can hold labels, icons, and any type of content inside,
  • Tabs can be modified to allow the user to close or reorder tabs in the tab view.