Usage guidelines
These tooltip guidelines apply to all data visualizations. For typography details on tooltips, see our page on typography.
Use tooltips to give users more details about data points.
Use tooltips to declutter your chart. If a specific piece of information is not the primary goal of your chart, consider making it available on demand. For example: if your axis labels consist of dates and the year is implied, you could only mention the year in the tooltip.
Only show tooltips on hover.
Spacing
Follow specific guidelines for tooltip spacing, as illustrated below:
Positioning
Tooltips should always be placed at "the end" of a chart. That is, on top for vertically-oriented charts and on the right for horizontally-oriented charts.
The tooltip is placed at the end of the corresponding bar and is centered to the label.
Placing a tooltip on top for a horizontally-oriented chart will prevent end users from seeing all the data.
Text wrapping
Sometimes, the text in a tooltip can get long. We recommend shortening your labels to reduce clutter and increase legibility. When it's not possible to shorten them, we keep the maximum width of the tooltip at 288px. In these cases, we only truncate the descriptor and not its corresponding value. Align items on the top and always keep 8px in-between for readability.
Content
The content displayed in tooltips should repeat the data values that are being hovered. In some cases, you might want to add additional relevant information. A tooltip typically consists of three parts: a header (1), a descriptor (2) and the descriptor’s corresponding value (3).
You can add an extra dimension if it adds value for end users. However, we advice against this for charts that display more than one category.
It's possible to add an additional metric for the same category. Only do so if it's useful information for end users.
Adding an extra dimension—when there is more than one category in the tooltip—makes it really difficult to read the data.
Behavior
Hover behaviors vary depending on the type of data visualization. As a general rule of thumb, bring focus to the element that is being hovered by dimming other elements. Additionally, we increase the hover area to make it more accessible. For chart-specific hover behaviors, see the corresponding pages of available charts.
A chart tooltip displays contextual extra information upon user interaction.
This component provides an implementation of the chart tooltip guidelines, along with a set of options and <slot>s to customize it.
Visualizations wrapped by an LumeChart component come with the default tooltip implementation, which shows the exact data value for each dataset in a hovered data point.
This component relies on the positioning logic from Popper.
Usage
Importing
import { LumeTooltip } from '@adyen/lume';
Basic use
To show a tooltip, provide a targetElement, an opened boolean and an array of items.
<lume-tooltip
:opened="true"
:targetElement="myElementRef"
:items="myItems"
/>
Default override
If you're using lume-tooltip to override the default implementation present in lume-chart, you'll have access to several slot properties you can use to define how you want the tooltip to behave.
Here's an example of overriding the default tooltip in a lume-line-chart:
<lume-line-chart
:data="myData"
:labels="myLabels"
>
<template #tooltip="{ opened, data, hoveredIndex, targetElement }">
<lume-tooltip
:opened="opened"
:items="myCustomItemsFunction(data, hoveredIndex)"
:target-element="targetElement"
/>
</template>
</lume-line-chart>
API
Props
| Name |
Type |
Default |
Description |
items |
Array<TooltipItem> |
Required |
An array of items to display. |
opened |
boolean |
false |
If the tooltip is visible or not. |
targetElement |
Element |
null |
A DOM element to attach to. |
position |
string |
"auto" |
Where the tooltip should be positioned relative to its target. |
fixedPositioning |
boolean |
false |
If true, it will use fixed positioning instead of absolute. |
modifiers |
Array<Modifier> |
null |
A list of modifiers for Popper. |
title |
string |
null |
The tooltip title. |
inverse |
boolean |
false |
If true, the tooltip items will be in inverse order. |
Note: the position prop only accepts valid placements. These are specified here.
Note: You can find more information about modifiers here.
Tooltip options
Interface: TooltipOptions
| Name |
Type |
Description |
| offset |
number |
Distance between the tooltip and its target element. |
| position |
string |
Where the tooltip should be positioned relative to its target. |
| showTitle |
boolean |
Controls if the tooltip title should be displayed. |
| targetElement |
Element |
A DOM element to attach to. |
| fixedPositioning |
boolean |
If true, it will use fixed positioning instead of absolute. |
| valueFormat |
string \| (tick: number \| string) => number \| string |
A format specifier string for d3-format or a formatting function. |
| summary |
string |
Descriptive text shown above the tooltip items. If a tooltip item is marked with isSummary, it will have precedence over this option. |
| withPointerEvents |
boolean |
If true, it will listen to the attached events on elements in the tooltip content. |
| inverse |
boolean |
If true, the tooltip items will be in inverse order. |
Note: Component properties have precedence over options. For instance, if you set the targetElement prop and the targetElement tooltip option, the first will be used. They're both there to cover different use cases.
Slot props
title
Slot for the tooltip header section.
No props.
summary
Slot for the tooltip summary item. Content of this slot should have a <li> element at its root.
No props.
items
Slot for the tooltip items. Content of this slot should be one or more <li> elements.
No props.
Events
opened
Fired upon tooltip initial render.
Payload
p: Element; // The tooltip's `targetElement` prop value.
moved
Fired upon tooltip targetElement change.
Payload
p: Element; // The tooltip's new `targetElement` prop value.
closed
Fired upon tooltip unmount.
tooltip-mouseenter
Fired upon mouse entering the lume tooltip.
tooltip-mouseleave
Fired upon mouse leaving the lume tooltip.
Payload
None.
