Implementation references
Scripting API and implementation references.
UI Toolkit
IMGUI
Overview
- 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
Guidance
When to use
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.
When to use tooltips vs help box
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.
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.
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.
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
Use tooltips when displaying concise information that can be summarized or explained in 3 lines or less.
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
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 utilize the shortcut manager to manage shortcuts, surfacing them to the user in context using a tooltip.
Content best practices
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.
Style
- 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.
Behavior
- 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
1. Hovered element
2. Container
3. Tooltip text
Layout
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.
Color
1. text
2. background-color
3. border-color
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 ->
See the accessibility section on tooltips ->
Code samples
Code references
Resources and related
