lib components / Overlay

Tooltip

Allow users to see a short, context-specific text message when they hover over or focus on an element

Tooltip vs. Popover Examples Properties Guidelines Notable Changes

import { Tooltip } from "@siteimprove/fancylab";

To clarify the differences between Tooltip and Popover, a short description is provided.

Component name	Usage
Tooltip	A tooltip is a short context-specific text message that appears temporarily when a user hovers or focuses on an element.
Popover	A popover is a customizable container that may contain interactive elements. It remains visible until the user clicks the close button, clicks outside of it, or tabs to the next focusable element.

#Examples

A Tooltip is a concise contextual message connected to an attached element, such as an icon or button, which offers supplementary information about it. By default, a Tooltip is hidden and become visible when hovered over or focused on an attached element. A Tooltip should be used sparingly, as it provides limited and specific information to an attached element.

A Tooltip consists of two elements:

Caret tip: a guide that directs the user's attention to the trigger that activated the Tooltip.
Container: the area that displays the additional information.

#Variant

Use the variant property to find out which variant suits your use case. The following sections explain how to use them.

Pay attention to user interaction with the Tooltip. Interactive variants are displayed only on focus state, whereas text and icon only variants require keyboard users to navigate to the attached element and press the Space Bar or Enter keys to display them.

Variant	Example	Use case
Text	DCI	Provides non-essential supplemental information to help users make decisions. For example, it can be used when data is missing from a table cell.
Icon only		Describes the meaning or purpose of icons without visible labels.
Interactive		Describes the function or action of an interactive UI element, such as a button.

#Text variant

Use the text variant to provide concise, relevant, and helpful information. The The tooltip's text should be clear and standalone, needing no additional explanation. Nest Tooltip inside the text's HTML or Fancy tags and wrap it around the string or number. Place the information in the content property of the component.

CodeHTML output

Theme: agentic-ai-2025

<InlineText>
	<Tooltip
		variant={{ type: "text" }}
		content="The Digital Certainty Index (DCI) is a measure of the quality and potential impact of a site's digital presence."
	>
		DCI
	</Tooltip>
</InlineText>

#Use a text variant in a card header

This is another contextual example with a text variant. It shows how to add a Tooltip to a Card header. However, if the user is unfamiliar with the title in the Card header, clearly display an explanation using small and subtle Inline text below a title in the Card header instead. See Best Practices.

WCAG

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ultricies nisl neque, ut feugiat arcu dapibus nec. Nulla facilisi. Ut scelerisque purus at tristique bibendum.

CodeHTML output

Theme: agentic-ai-2025

<Card>
	<Card.Header>
		<H2>
			<Tooltip
				variant={{ type: "text" }}
				content="Web Content Accessibility Guidelines (WCAG) is developed through the W3C process in cooperation with individuals and organizations around the world, with a goal of providing a single shared standard for web content accessibility that meets the needs of individuals, organizations, and governments internationally."
			>
				WCAG
			</Tooltip>
		</H2>
	</Card.Header>
	<Content>
		<Paragraph>
			Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ultricies nisl neque, ut
			feugiat arcu dapibus nec. Nulla facilisi. Ut scelerisque purus at tristique bibendum.
		</Paragraph>
	</Content>
</Card>

#Change an icon in a text variant

Use the icon property to change the icon in a Tooltip. The default icon is IconHelpOutline, aliased as Tooltip.icon. It is highly recommended to stick to the default icon for better user recognition and consistency.

CodeHTML output

Theme: agentic-ai-2025

<InlineText>
	<Tooltip
		variant={{
			type: "text",
			icon: (
				<Icon size={Tooltip.iconSize}>
					<IconPotentialIssue />
				</Icon>
			),
		}}
		content="Potential issues need to be verified by a human being."
	>
		Potential issue
	</Tooltip>
</InlineText>

#Change an icon size in a text variant

Use the size property of the Icon component to adjust the size of the tooltip icon. This enables you to match the size of the tooltip icon with its associated text. The default value is medium, aliased as Tooltip.iconSize.

CodeHTML output

Theme: agentic-ai-2025

<InlineText size="large">
	<Tooltip
		variant={{
			type: "text",
			icon: <Icon size="large">{Tooltip.icon}</Icon>,
		}}
		content="An SEO Activity Plan is a toolbox for customizing an adjustable workflow, allowing users to engage with all aspects of Search Engine Optimization (SEO) to meet their website goals and challenges."
	>
		Activity plans
	</Tooltip>
</InlineText>
<br />
<InlineText size="medium">
	<Tooltip
		variant={{
			type: "text",
			icon: <Icon size="medium">{Tooltip.icon}</Icon>,
		}}
		content="An SEO Activity Plan is a toolbox for customizing an adjustable workflow, allowing users to engage with all aspects of Search Engine Optimization (SEO) to meet their website goals and challenges."
	>
		Activity plans
	</Tooltip>
</InlineText>
<br />
<InlineText size="small">
	<Tooltip
		variant={{
			type: "text",
			icon: <Icon size="small">{Tooltip.icon}</Icon>,
		}}
		content="An SEO Activity Plan is a toolbox for customizing an adjustable workflow, allowing users to engage with all aspects of Search Engine Optimization (SEO) to meet their website goals and challenges."
	>
		Activity plans
	</Tooltip>
</InlineText>

#Use a text variant to explain no data

Use a text variant to explain the absence of data in a table cell or similar location, with a brief explanation provided.

CodeHTML output

Theme: agentic-ai-2025

<Tooltip
	variant={{ type: "text" }}
	content="The page doesn't contain enough text to measure readability."
>
	Unavailable
</Tooltip>

#Icon only variant

Use the icon-only variant for clear and concise descriptions of static icons. Wrap the Tooltip around the Icon and put the label in the content property.

Only provide a static icon with a Tooltip, instead of a visible label, when:

The label doesn't contain information essential to task completion.
Placing label in the UI would add significant visual clutter.

CodeHTML output

Theme: agentic-ai-2025

<Tooltip variant={{ type: "icon-only" }} content="Desktop device">
	<Icon>
		<IconDesktop />
	</Icon>
</Tooltip>

#Use an icon only variant to explain no data

The icon only variant can be used when there is no accompanying text, but only as a last resort due to technical difficulties. It is recommended to include a text snippet.

CodeHTML output

Theme: agentic-ai-2025

<Tooltip variant={{ type: "icon-only" }} content="No data available">
	<Icon size={Tooltip.iconSize}>{Tooltip.icon}</Icon>
</Tooltip>

#Interactive variant

For interactive UI elements lacking a label, utilize the interactive Tooltip to clarify their purpose or action. Wrap the Tooltip around the element and provide clarification in the content property. An example of this is an icon-only button, as shown below.

Only provide interactive UI elements with an icon, instead of a visible label, when:

Space in the UI is limited and/or the UI element is repeated many times on the page.
The icon is universally known, such as a trash can for deleting.

CodeHTML output

Theme: agentic-ai-2025

<Tooltip variant={{ type: "interactive" }} content="Delete item">
	<Button onClick={() => console.log("clicked")}>
		<Icon>
			<IconDelete />
		</Icon>
	</Button>
</Tooltip>

#Placement

Position a Tooltip using the placement property to avoid obstructing relevant information crucial to the user's task. The Tooltip offers 12 placement options, with top as the default. A Tooltip can also be positioned to the right, left, bottom of the trigger element.

Keep in mind that the Tooltip will only appear in the preferred placement if there's enough space available.

CodeHTML output

Theme: agentic-ai-2025

<Tooltip
	variant={{ type: "text", learnMoreAbout: "this tooltip's preferred placement" }}
	content="My preferred placement is to the right."
	placement="right"
>
	<InlineText>Tooltip placement</InlineText>
</Tooltip>

#Properties

CodePropsHTML output

Theme: agentic-ai-2025

Property	Description	Defined	Value
variantRequired	`object`text, icon-only, or interactive. Please read the styleguide documentation for guidance.	YesNo
contentRequired	`\| string \| number \| element`Content to display when the tooltip is active	YesNo
childrenOptional	`\| string \| number \| object \| element \| object`The element that the tooltip clarifies the function or meaning of	YesNo
placementOptional	`"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"`Preferred placement for the tooltip when active	YesNo
aria-labelOptional	`string`Override the aria-label for the button wrapping the anchor element. Only use aria-label for the “icon-only” variant in special cases, since it overrides the content of the HTML element inside of the tooltip	YesNo
aria-describedbyOptional	`\| string`Override the aria-describedby for the button wrapping the anchor element	YesNo
onHideOptional	`function`Callback that's executed after the tooltip content gets hidden	YesNo
forceOpenOptional	`boolean`Force the tooltip to be in its visible state	YesNo	truefalse
noDelayOptional	`boolean`Remove the delay when showing and hiding the tooltip	YesNo	truefalse
hideContentOptional	`boolean`Hide the content visually and for assistive technology	YesNo	truefalse
updateKeysOptional	`unknown[]`Key to control updates to the placement of the popover. Provide a different value when an update is desired	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

Table
Use a Tooltip in a Column header to clarify the meaning of the data. For instance, in the case of the "Search Volume" column in SEO Keyword Discovery, the Tooltip can explain it as the monthly search count for a keyword.
Form
Use a Form Element Wrapper with help text to present crucial task information, and a Tooltip for further explanation of the meaning of the label or the need for requested information. Avoid repeating the help text in the Tooltip.
Highlight important data and metrics
Tooltips can be utilized in the Highlight and DCI gauge components to emphasize crucial data and metrics. They can also clarify taxonomy or product terminology, for example, in the Ads Overview, a Tooltip is used to explain "Return on Ad Spend".
Card header
A Tooltip can be used for a title in the Card header. However, it is recommended to display the explanation using small and subtle Inline text below a title in the Card header for clarity. As an example, in Analytics, the definition of Key Metrics is displayed below a title in the Card header.
Card content
When the information is compact in the Card, you can use the text variant with Inline text. For example, in Accessibility Overview, the Tooltip is used with the Inline text "Progress towards site target" above the Progress bar.

#Style

Tooltips' text wraps automatically if its content exceeds the maximum width of 48ch.
Ensure consistency in using tooltips, and consider if similar elements also need one.
Avoid styling the content in tooltips, stick to plain text and avoid images, complex styling, or links that may distract the user from the message.

#Do not use when

displaying important information needed to complete a task. The important information should be visible on the page and not hidden in a Tooltip. Use subheadings, inline text, or persistent.
including actions. Use the Popover and disclosure pattern for elements like Button or Link that need to be part of additional information.
presenting longer help content. Use a Learn Info Box component or the Help Center.
introducing new features, and explaining how to use them.
displaying rrror or status messages, images, interactive content, obvious interactions, or irrelevant information.
a page title requires additional explanation, it may not be suitable. Rewrite the title accordingly.

#Accessibility

For designers

A Tooltip may reduce UI clutter, but their use can greatly decrease accessibility for screen reader users. Always consider alternatives before using a Tooltip.
A Tooltip must only include text and avoid interactive elements.
Avoid covering important content and place vital information in a Tooltip.
Make sure the information in the Tooltipaccurately describes the attached element.

For developers

Avoid adding a title attribute to elements within a Tooltip to avoid duplicate tooltips.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Tooltips should be concise with only essential information to understand the element. Ideally no more than one or two sentences. See writing example .
Ensure the content is clear and understandable without technical terms.
The tooltip should be relevant to the attached element, avoiding redundant information.
Use sentence case, and only use periods if the text contains complete sentences.

It's now required to choose from one of four Tooltip variants:
- text
- icon-short-label
- icon-long-label
- interactive
The interactive variant replaces the Instant Tooltip Wrapper component.
The anchor property has been removed. The Tooltip should now always be wrapped around its associated UI element.
The Tooltip now always comes with an aria-label. It’s (partly) set with the variant property’s learnMoreAbout parameter for the text and icon-long-label variants. It’s automatically set for the icon-short-label and interactive variants.
Eight new value options have been added to the placement property.
It’s now possible to change both the Tooltip icon and its size, when using the text variant, with the icon property.

Tooltip

# Tooltip vs. Popover

#Examples

#Variant

#Text variant

#Use a text variant in a card header

WCAG

#Change an icon in a text variant

#Change an icon size in a text variant

#Use a text variant to explain no data

#Icon only variant

#Use an icon only variant to explain no data

#Interactive variant

#Placement

#Properties

#Guidelines

#Best practices

#General

#Placement

Table

Form

Highlight important data and metrics

Card header

Card content

#Style

#Do not use when

#Accessibility

For designers

For developers

#Writing

#Notable Changes

#Version 47.0.0

#Version 0.0.x