Tooltip

What is this?

Tooltip containers allow merchants to contextually understand the definition of an item through an overlay.

Text

Target

You can change the tooltip target through children.

Visible

Use the visible prop to make the tooltip a controlled component.

Placement

You can use the placement property to change the position that the Tooltip popup will appear

Usage

import { Tooltip } from '@vtex/admin-ui'

function Example() {
  return <Tooltip text="Tooltip text" />
}

Tooltip Props

Name	Type	Description	Required	Default
text	string	Text shown inside the tooltip	✅	-
children	ReactNode	The element that triggers the tooltip	🚫	-
placement	auto-start, auto, auto-end, top-start, top, top-end, right-start, bottom, or left	The placement of the tooltip relative to its children	🚫	top
visible	boolean	Whether the tooltip is visible or not	🚫	false
csx	StyleProps	Custom styles	🚫	{}
bleedX	boolean	Horizontal bleed	🚫	false
bleedY	boolean	Vertical bleed	🚫	false

Accessibility

Tooltip has role="tooltip".
Tooltip's children has aria-describedby referring to the Tooltip.
Esc hides the current visible tooltip.

Components

When to display instructions in an overlay, in the Page itself or in an external link?

• Choose overlays (such as a Modal, a Tooltip or a Popover) for components that don't support inline instructions, such as the label in a Table column or the label of a Totalizer.
• Also choose overlays for information that is important to understand the interface and can't be reduced, such as to explain how the data of a graph is collected.
• Choose to add content in the Page itself (in a description or help text) when the instruction is short and doesn't affect the flow of the page. Consider that the instructions must follow each component's Content guidelines.
• Choose an external link for extensive information that isn't essential for the flow of the page, such as to provide more details on a new concept or step-by-step instructions. For example, documentation explaining the concept of Core web vitals.

When to use a Popover or a Modal instead of a Tooltip?

• Choose a Popover when the instruction includes text longer than 240 characters or elements that have interaction, such as a Button or a Link.
• Choose a Modal when the instruction requires full attention or is part of a Modal flow. For example, a confirmation modal or an onboarding Modal.

Variants

When to use the default Tooltip trigger or a custom trigger?

• In most cases, you should use the default Tooltip trigger with the question mark because it is known for representing instructions in the Admin.
• When information is truncated according to the content guidelines of a component, a custom trigger can be used to expand it contextually.

What to avoid:

• Don't use a Tooltip to show the label of a Button with only an icon.

Position

Where should the Tooltip open?

• The Tooltip opens on top of the trigger by default, but its placement is automatically adjusted according to the available space.
• Adjust the preferred placement of the Tooltip so it doesn't hide important content around it.

Where should a Tooltip trigger be positioned?

On left-to-right interfaces, it should be positioned on the right of a label or title.

What to avoid:

Don't position a Tooltip next to an element that isn't a descriptive Text. For example, don't place it on the right side of a Text Input. Place it next to its label instead.

Behavior

When should a Tooltip open?

A Tooltip should always open on hover. If the content includes elements that have interaction, use a Popover that opens on click instead.

Content

What should be the content of a Tooltip?

• Write the Tooltip text as if you are answering the following question: What does this mean?
  For example, for a Sessions Totalizer, the Tooltip text can be Visits to the store that can include a series of user interactions and end after 30 minutes of inactivity.
• Start with a noun followed by additional information, such as conditions and definitions.
• Use sentence case, but capitalize proper nouns.
• Prefer using a single sentence that is short and direct.

What to avoid:

• Don't write text longer than 240 characters.
• Don't repeat the label.
• Don't explain the benefits of the content, only its meaning.
• Don't use periods.

• What is this?
• Text
• Target
• Visible
• Placement