Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { Tooltip } from '@uhg-abyss/web/ui/Tooltip';

content

position

variant

delayDuration

<Tooltip content="Information goes here">
  <Button aria-label="Tooltip information" icon={{ icon: 'question_mark', position: 'icon-only' }} />
</Tooltip>

Content

Use the content prop to insert a text description that appears on pointer hover or keyboard focus.

asChild

Using asChild prop will merge the original component props with the props of the supplied element/component and change the underlying DOM node. The default value is true. Set asChild to false to render tooltip on static elements.

Position

Use the position prop to change the position of the tooltip. Options include 'left', 'right', 'top', and 'bottom'. The default position is 'bottom'.

Note: When the tooltip cannot fit in the screen at the provided position, it will dynamically change orientation to fit.

Delay duration

Use the delayDuration prop to control the time it takes for the tooltip to open. The default is 300 milliseconds. Setting the delayDuration to 0 will render tooltip instantly. Maximum delayDuration is 700 milliseconds.

Variant

Use the variant prop to choose the color variant of the tooltip. The default is 'gray', the other option is 'white', which sets a white background.

When should I use a tooltip vs a popover?

Glad you asked! There are several considerations when deciding between a Tooltip or a Popover:

Purpose of content

• A Tooltip is a hint or a tip about what an interactive element does. Tooltips are meant to help clarify or provide supplementary instruction for an element on hover or upon receiving focus. They should not be used to add additional content nor should they include interactive elements such as links. Tooltips should not receive mouse or keyboard focus. Try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding WCAG 2.1 SC 1.4.13: Content on Hover or Focus

• A Popover should be used to provide additional content to static text, such as definitions of words, informational blurbs, or additional product details. They can receive focus and can contain links and other interactive elements.

Size of content

• Since Tooltips are only meant to tell the purpose of an element they should be short and to the point, for example: "Click X to do X" or "User post count".

• Popovers, on the other hand, can be much more verbose, they can include a heading, lines of text in the body, links, etc.

Interactions

• Tooltips should only be visible on mouse hover or upon receiving focus. For this reason, if you need to be able to read the content while interacting with other parts of the page then a Tooltip will not work. They should be dismissible using the "escape" key. They should be used on interactive elements where a mouse click or keyboard activation would otherwise trigger the elements primary function.

• Popovers must be triggered to appear, whether via mouse click or via keyboard navigation. They must be dismissible, whether by clicking on other parts of the page, clicking the Popover target, or a specific close button/icon (depending on implementation). For this reason, you can set up a Popover to allow you to interact with other elements on the page while still being able to read its content. On top of this, since Popovers will remain open when mousing out of their target, you can add additional buttons or interactions within them.

Mobile screens

Tooltips only work on mouse hover (or keyboard focus). Since mobile users can't hover, the tooltip won't appear, rendering it ineffective and leading to a poor user experience where essential information might be inaccessible. Instead, we recommend using our Popover component for a better mobile experience. Also, bear in mind that mobile screens are smaller, so please keep your content concise to ensure readability.

Conclusion

If you want to give a short hint or supplemental instructions for an interactive element (such as a submit button), use a Tooltip.

If you want to add additional content to a static element that might include headings, body text, links, etc, and you need the content to remain open even after mousing away or the element losing focus, then use a Popover.

It should be noted that any vital information users need to complete an action or make a decision should be displayed directly in the page text or button label, rather than a Tooltip or a Popover. Critical information hidden in a Tooltip or a Popover might not be discovered by all users and could create accessibility issues.

Tooltip Props

Name	Type	Default	Required	Description
ariaLabel	string	-	-	The aria-label for the Tooltip
asChild	boolean	true	-	If true, the Tooltip props will be merged with the trigger element
children	React.ReactNode	-	-	The trigger element of the Tooltip
className	string	-	-	CSS class name to apply to each element within the component
content	React.ReactNode	-	-	The content of the Tooltip
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
delayDuration	number	300	-	The time (in milliseconds) between the trigger being hovered and the Tooltip appearing
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
position	"top" | "bottom" | "left" | "right"	'bottom'	-	The side of the trigger element where the Tooltip will appear
variant	"gray" | "white"	'gray'	-	The color variant of the Tooltip

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Tooltip.types.ts

Tooltip Classes

Class Name	Description
.abyss-tooltip-root	Tooltip root element
.abyss-tooltip-trigger	Tooltip portal element
.abyss-tooltip-portal	Tooltip trigger element
.abyss-tooltip-content	Tooltip content element
.abyss-tooltip-arrow	Tooltip arrow element

Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but are otherwise not visible on the page. While a Tooltip can be placed on any content, they are intended to be used for controls or small visual elements, such as providing additional content for icons with a brief label (or no label at all, which is not accessible!). From an accessibility and usability perspective, try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding WCAG 2.1 SC 1.4.13: Content on Hover or Focus.

Instead of using tooltips and hiding important information, if you have the space, consider writing clear, succinct, always-visible descriptions such as labels and body text. Check out the Mozilla tooltip role docs to learn more.

Adheres to the Tooltip WAI-ARIA design pattern.

Keyboard Interactions

Key	Description
Tab	Opens/closes the tooltip without delay.
Escape	If open, closes the tooltip without delay.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

Tooltip Tokens

Token Name	Value
tooltip.color.border.light	#CBCCCD
tooltip.color.surface.light	#FFFFFF
tooltip.color.surface.dark	#4B4D4F
tooltip.color.text.label.light	#4B4D4F
tooltip.color.text.label.dark	#FFFFFF
tooltip.border-radius.all.container	4px
tooltip.border-width	1px
tooltip.spacing.padding.horizontal.container	12px
tooltip.spacing.padding.vertical.container	8px
tooltip.spacing.padding.notch	4px
tooltip.elevation	0px 6px 8px -2px rgba(0,0,0,0.16)