Tooltip
- Usage
- Styling
Tooltips are small pop-ups for providing additional information about other UI elements. A tooltip for an element becomes visible when the user hovers the mouse pointer over the element or when the element receives keyboard focus.
new tab
<TextField placeholder="Search">
<Icon icon="lumo:search" slot="prefix" />
<Tooltip slot="tooltip" text="Wrap in “quotes” for exact phrase" />
</TextField>
Tooltips only support plain text content. They aren’t focusable and can’t contain interactive elements.
Other UI Elements
Tooltips can be displayed for UI elements that lack a dedicated tooltip API. Proper accessibility, however, for these can’t be guaranteed.
new tab
<h2 id="heading">Heading with tooltip</h2>
<Tooltip for="heading" text="This is a tooltip" position="top-start" />
Positioning
The default positioning of the tooltip in relation to the target element can be overridden. This can be useful for optimizing where the tooltip is rendered, to avoid overlaying other important UI elements, or for purely aesthetic reasons.
new tab
<Tabs slot="drawer" orientation="vertical">
<Tab>
<a tabIndex={-1}>
<Icon icon="vaadin:home" />
</a>
<Tooltip slot="tooltip" text="Home" position="end" />
</Tab>
<Tab>
<a tabIndex={-1}>
<Icon icon="vaadin:calendar" />
</a>
<Tooltip slot="tooltip" text="Calendar" position="end" />
</Tab>
<Tab>
<a tabIndex={-1}>
<Icon icon="vaadin:chart" />
</a>
<Tooltip slot="tooltip" text="Reports" position="end" />
</Tab>
</Tabs>
The distance between the tooltip and the target element can also be customized by setting the following CSS properties on the tooltip:
-
--vaadin-tooltip-offset-top
-
--vaadin-tooltip-offset-bottom
-
--vaadin-tooltip-offset-start
-
--vaadin-tooltip-offset-end
Configuring Delays
The delay before tooltips appear can be configured separately for hover and keyboard focus. The delay before tooltips disappear — when the pointer leaves the target element — can also be configured separately. On blur, though, the tooltip is closed immediately to avoid confusion when focusing another element.
import { Tooltip } from '@vaadin/tooltip';
// Global delay configuration:
Tooltip.setDefaultFocusDelay(2000);
Tooltip.setDefaultHoverDelay(1000);
Tooltip.setDefaultHideDelay(1000);
// Overriding delays for a particular component’s tooltip:
<Button>
Click me
<Tooltip hoverDelay={500} slot="tooltip" text="Home" />
</Button>
Triggering Manually
Tooltips can be configured not to appear automatically on hover or keyboard focus, but instead be programmatically triggered only. This can be used to create so-called, toggletips — tooltips that can be manually displayed and hidden by the user.
new tab
<TextField placeholder="Search">
<Icon slot="prefix" icon="lumo:search" />
<Tooltip
slot="tooltip"
text="Wrap in “quotes” for exact phrase"
manual
opened={tooltipOpened}
/>
<Button
slot="suffix"
theme="tertiary-inline icon"
onClick={() => setTooltipOpened(!tooltipOpened)}
>
<Icon icon="vaadin:info-circle" />
</Button>
</TextField>
Accessibility
Tooltips are semantically associated with their target elements using the aria-describedby
attribute, and are announced by screen readers when the element gains keyboard focus.
However, tooltips on elements without dedicated tooltip APIs can’t be guaranteed to be announced correctly. This is because the announcement of aria-describedby
attributes depends on the HTML element’s type and the role
attribute. It also varies between different screen readers. Testing with screen readers is useful to ensure the accessibility of tooltips on these elements.
The tooltip feature currently doesn’t support triggering via long press on touch-screen devices.
Keep in mind that Vaadin components and other UI elements don’t, by default, imply the presence of tooltips in any way. This might make them difficult for users to discover.
In general, visible labels are always preferable to tooltips. A separately defined invisible aria-label
attribute usually provides better accessibility than a tooltip.
Best Practices
Tooltips should be used only to provide additional information, not for mission-critical information. They’re not a replacement for visible labels on input fields.
On input field components, tooltips should be considered a last resort if neither the label — not the helper — nor the placeholder text can be used to provide the necessary information.