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

Tooltip · UX essentials

Essential guidance on tooltip usage in the Editor.

Tooltips display contextual help for all UI elements
US-0240
Blue plus sign icon indicating that clicking on this will expand this content
In Inspector-like windows, input controls should have labels and tooltips
Blue plus sign icon indicating that clicking on this will expand this content
Tooltips are written in clear, complete sentences
US-0241
Blue plus sign icon indicating that clicking on this will expand this content

Overview

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 over 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

Illustration of the defining tooltips using UI Builder
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}
UI Toolkit
myVisualElement.tooltip = “Hello World!”;
You can define a tooltip on any VisualElement by using the .tooltip property
Tooltips in IMGUI
IMGUI
GUIContent.tooltip
If a UI component can take GUIContent as an argument, a tooltip may be passed to the UI component as a property of GUIContent

Guidance

When to use

Various use cases for tooltips

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

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. See the Unity Standard on truncated text (work-in-progress) ->

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.
See the Unity Standard on alt text (work-in-progress) ->

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. See the Unity Standard on disabled UI ->

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. See the Unity Standard on action shortcuts ->

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 tooltips are hidden by default, prioritize 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 three 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.

Unity standards on shortcuts;

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 a period at the end of a tooltip only if it's a complete sentence. If any tooltip has a second sentence, all sentences in the tooltip require a period.
  • 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.
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
Icon displaying the Unity logo
Docs Style Guide

Check the text for typos, voice, and capitalization

unity-docs.gitbook.io

Arrow icon indicating link goes to an external source

Style

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 three 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

Behavior

Animation showing the delay time between hovering over an element and when the tooltip appears
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

Formatting

Anatomy and layout

Anatomy
A tooltip and its parts

1. Hovered element
2. Container
3. Tooltip text

Layout
Tooltips appear horizontally centered and 10 px below the hovered element

Tooltips appear horizontally centered, and 10 px 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.

Color

1. Tree view item Label / 2. Foldout Arrow / 3. Icon
1. text
--unity-colors-default-text
The default text color
#090909
#D2D2D2
2. background-color
--unity-colors-tooltip-background
The background color for a tooltip.
#DEDEDE
#373737
3. border-color
--unity-colors-tooltip-border
The border color for a tooltip
#8A8A8A
#191919

Accessibility

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