Tooltip

<zeno-tooltip>OverlaysSource

A short text description that appears when the slotted element is hovered or focused. Built on a native popover.

import '@usezeno/tokens/css';
import '@usezeno/core/web-components';

Examples

Basic

Wrap one element and set the text with content. The tooltip shows when the pointer rests on the element or when the element gets keyboard focus. These examples wrap a native <button>.

<zeno-tooltip content="Copy the link to this page">
  <button type="button">Copy link</button>
</zeno-tooltip>

Placement

placement is the side you prefer. The tooltip moves to the opposite side when there is no room.

<zeno-tooltip content="Shown above" placement="top">
  <button type="button">Top</button>
</zeno-tooltip>
<zeno-tooltip content="Shown on the right" placement="right">
  <button type="button">Right</button>
</zeno-tooltip>
<zeno-tooltip content="Shown below" placement="bottom">
  <button type="button">Bottom</button>
</zeno-tooltip>
<zeno-tooltip content="Shown on the left" placement="left">
  <button type="button">Left</button>
</zeno-tooltip>

Delay

delay is the time in milliseconds before the tooltip shows for the pointer. The default is 200. Keyboard focus shows it at once.

<zeno-tooltip content="Shown at once" delay="0">
  <button type="button">No delay</button>
</zeno-tooltip>
<zeno-tooltip content="Shown after one second" delay="1000">
  <button type="button">Long delay</button>
</zeno-tooltip>

Disabled

A disabled tooltip does not show. The wrapped element still works.

<zeno-tooltip content="This text does not show" disabled>
  <button type="button">No tooltip</button>
</zeno-tooltip>

Attributes and properties

Property	Attribute	Type	Default	Description
content	content	string	''	The text of the tooltip.
placement	placementreflects	'top' | 'right' | 'bottom' | 'left'	'top'	The preferred side. The tooltip moves to the other side when it would not fit.
delay	delay	number	200	How long the pointer rests on the element before the tooltip shows, in ms.
disabled	disabled	boolean	false	Turns the tooltip off. The wrapped element is not affected.
testId	–	string	–	Test ID for automated testing From ZenoElement.

Methods

Method	Description
show(delay): void	Shows the tooltip after delay milliseconds.
hide(delay): void	Hides the tooltip, after a moment by default so the pointer can reach it.
focus(): void	Focus the component or its first focusable element From ZenoElement.
blur(): void	Blur the component or its focused element From ZenoElement.

Events

Event	Detail	Description
show	–	The tooltip appeared.
hide	–	The tooltip went away.

Slots

Slot	Description
Default	The element the tooltip describes.

CSS parts

Part	Description
tooltip	The bubble.

CSS custom properties

This element documents no custom properties of its own. Style it through its parts and through the tokens it reads.

The element's own source reads no tokens.

Accessibility

Keyboard

Key	What it does
Tab	Moves focus to the wrapped element. The tooltip shows at once, and hides when focus leaves.
Escape	Hides the open tooltip. The key press is not stopped, so other listeners on the page also get it.

Forms

This element is not a form control. It adds nothing to a form's data.

Notes

• The text is set as aria-description on the first wrapped element. The text itself is used because an id reference cannot cross the shadow root.
• The bubble has aria-hidden="true", so the text is read once, as the description.
• The tooltip shows for keyboard focus only when the wrapped element matches :focus-visible. A mouse click does not leave a tooltip open.
• The pointer can move from the element onto the bubble, and the bubble stays open. Escape, scrolling, and moving the pointer or focus away close it.
• In forced colours mode the bubble gets a border.

Tests and known gaps

• Tested in a real browser by tooltip.test.ts.
• Checked with axe-core in the light and the dark theme.
• Has no Storybook story.

Known gaps:

• Around <zeno-button> and other Zeno controls that pass focus to an inner control, the tooltip does not show for keyboard focus. It shows for the pointer only.
• Around a Zeno control, aria-description is set on the host element. It does not reach the inner native control, which is the element that has focus.
• Only the first wrapped element gets the description and is used for the position. Plain text with no element around it gets no description.
• The placement type lists top, right, bottom and left. The code also reads top-start, top-end, bottom-start and bottom-end, which the type does not list. A suffix on left or right is ignored.
• The position is set once, when the tooltip opens. It is not set again when content or placement change or when the window is resized while the tooltip is open.
• The text can only come from the content attribute. There is no slot for the bubble, so it cannot hold markup.