Implementation references

Scripting API and implementation references.

UI Toolkit

Tooltips · UX essentials

Essential guidance on tooltip usage in the Editor.

In Inspector-like windows, input controls should have labels and tooltips
Blue plus sign icon indicating that clicking on this will expand this content


A tooltip displays on a label when the user hovers on it.
  • Tooltips are not stand alone controls: they are always linked to the UI component that triggered them
  • Tooltips concisely display contextual help or information about an element when users hover on it
  • Tooltips are transient, concise, and easily scanned, helping the user understand the interface and available actions without having to refer to a manual or leave the Editor environment
  • In the Editor, tooltips currently only contain text strings; they cannot contain icons or images

Tooltips in Editor frameworks

Tooltips in UI Toolkit

You can define the tooltip in the Attributes section of a VisualElement’s Inspector.
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


myVisualElement.tooltip = “Hello World!”;
You can define a tooltip on any VisualElement by using the .tooltip property
Tooltips in IMGUI
API in


If a UI component can take GUIContent as an argument, a tooltip may be passed to the UI component as a property of GUIContent


When to use

Various use cases for tooltips
Icon of a letter I in a blue circle indicating this is a piece of informational content
Tooltips in play mode
Tooltips are not displayed when the Editor is in play mode

Tooltips give additional information about the UI element that triggers it, helping the user with progressive complexity as they need it. Some common use cases to consider are:

New users

Consider that both new and experienced users may use the feature. While some functionality may be obvious to experienced users, new users may need more guidance. Use tooltips to give guidance.

Truncated text

When the UI is resized or on smaller screen sizes, text may be cut off. Use tooltips to allow the user to access the full string without resizing their UI.

Images or icons without labels

A new user, a user using a screen reader, or a user that uses an icon-heavy interface regularly may not know what the icon may represent. Use tooltips to assign a label to the icon.
The tooltip for the icon should always include the label/name, for example: Print tool: Print this page.

Disabled UI

When UI is disabled, a user cannot interact with it and may not know why it is disabled. Use tooltips to provide an explanation for why the UI is disabled, and how they may enable it.

Keyboard shortcuts

Users may not know that a keyboard shortcut exists for some tools. Use tooltips to encourage the use of keyboard shortcuts in context.

When to use tooltips vs help box

Do recommendation illustrated by a green checkbox icon

Use tooltips when displaying contextual information that is not vital to the user’s workflow, as it is only accessible if a user hovers over the relevant UI. As it is hidden by default, favour tooltips over informational (log) messages in help boxes to avoid cluttering the UI when communicating non-critical information.

Do recommendation illustrated by a green checkbox icon

Use informational (log) messages when it is important for a user to discover helpful advice that is not essential to the operation, but that they may not discover it if it is hidden in a tooltip.

Don't recommendation illustrated by a red X icon

Do not use tooltips to indicate when the function will complete an action but may return results that are not what the user intended. Use a warning message instead.

Don't recommendation illustrated by a red X icon

Do not use tooltips to indicate when a function will not complete an action. Use an error message instead.

When to use tooltips vs reference documentation

Do recommendation illustrated by a green checkbox icon

Use tooltips when displaying concise information that can be summarized or explained in 3 lines or less.

Do recommendation illustrated by a green checkbox icon

Use a link to reference documentation if the information that needs to be displayed is multiple paragraphs, has an example, or requires images or videos to explain.

How to Use

Don't recommendation illustrated by a red X icon

If including a keyboard shortcut in the tooltip, do not hard code the keyboard shortcut into the tooltip string, as it will not update if the user personalizes their keyboard shortcuts.

Do recommendation illustrated by a green checkbox icon

Do utilize the shortcut manager to manage shortcuts, surfacing them to the user in context using a tooltip.

Content best practices

Tooltips showing only description, and full name of object and a description/message.
Truncated text in tooltips

When a text is truncated, the full text appears in its tooltip on hover. When adding both the full label and a description in a tooltip, make sure label comes first with a line break.

Writing style and terminology

General guidance on writing style and terminology for all technical reference communication at Unity.

  • Write tooltips in complete sentences and terms, not shorthand or abbreviations
  • Use full punctuation in all sentences
  • Do not use system language or domain jargon; assume that users are unfamiliar with the feature and domain
  • Do not use tooltips as a replacement for documentation. In-depth instruction on how to use a feature should be kept in documentation; only use guiding information in a tooltip
  • All fields/controls should have a tooltip
  • Tooltips should be less than three lines long
  • Check the text for typos, voice, and capitalization.


Style elements and content layout of a tooltip
  • The maximum width of a tooltip is 300 px
  • The height of a tooltip is dependent on the tooltip contents; tooltips should be concise, and no longer than 3 lines. Long tooltips are not readable or usable
  • Tooltip text is left-aligned
  • Tooltips have a border of 1 px
Tooltips are drawn by the operating system

Tooltips are drawn as floating windows and their style varies based on how the operating system draws floating panels.

Tooltips rendered in macOS and Windows platforms


Tooltips appear after a 0.4 second delay.
  • A tooltip appears 0.4 seconds after the cursor pauses on a component that has a tooltip, and remains for as long as the cursor is on the component
  • If the cursor leaves the component onto a UI that does not have a tooltip, the tooltip disappears immediately; the next time a tooltip is triggered, it will appear after 0.4 seconds of delay
  • If the cursor leaves the component directly onto the UI that has a tooltip, the original tooltip disappears immediately, and the new tooltip appears immediately without delay


Anatomy and layout

A tooltip and its parts

1. Hovered element
2. Container
3. Tooltip text

Tooltips appear horizontally centered and 10 px below the hovered element

Tooltips appear horizontally centered, and 10px below the bottom edge of the element that triggered it.

If this positioning causes the tooltip to appear out of the bounds of the screen, it will reposition itself so that the entire tooltip is displayed.

Interaction states

Tooltips are transient, and only appear on hover on the element that triggers it.


1. Tree view item Label / 2. Foldout Arrow / 3. Icon
1. text
The default text color
2. background-color
The background color for a tooltip.
3. border-color
The border color for a tooltip


Tooltips as icon labels

A new user, a user using a screen reader, or a user that uses an icon-heavy interface regularly may not know what the icon may represent. Use tooltips to assign a label to the icon. See the accessibility section on alt text ->

Code samples