A tooltip gives an icon-only button a short name when the user hovers it or moves keyboard focus to it. Esc hides it.
How to add a tooltip to a page. The files are components/css/tooltip.css and components/js/tooltip.js.
Link the shared files once per page. Never copy the rules, and never write a tooltip script of your own: a page that does (for example a row-tooltip) fights the shared one over the position.
| Step | What to do |
|---|---|
| 1. Link | <link rel="stylesheet" href="/components/css/tooltip.css"> and <script src="/components/js/tooltip.js"></script>. Both templates (template.html, mypages/mypages-template.html) already have them. |
| 2. Choose | Global (recommended for icon buttons, table rows and anything built in JS): add data-tooltip="Label" to the element. Markup (.tooltip-wrap + .tooltip): when you need a specific type or size (start, end, left, right, Large, Body), or a tooltip that is part of the page markup. |
| 3. Name the control | Give the button an aria-label with the same text as the tooltip. The tooltip itself is not announced. |
data-tooltipOne shared tooltip is shown for any element with data-tooltip, including elements you add later. It is a popover in the top layer, so no overflow, z-index or stacking context can clip it or hide it. It is centered on the element, aligns to the start or end of it (as shown under Layout & Appearance in Examples & Guidelines) when it would leave the viewport sideways, and flips above or below when there is no room.
data-tooltip, the second adds data-tooltip-position="bottom"..tooltip-wrapClasses name where the tooltip sits next to the element: tooltip--top and tooltip--bottom (automatic), --top-start, --top-end, --bottom-start, --bottom-end, --left, --right, --left-start, --right-start and --body (always manual). tooltip--lg is Large. tooltip--manual keeps a Top or Bottom tooltip fixed and centered, and tooltip--flip, tooltip--align-start and tooltip--align-end are added by tooltip.js: never write them yourself.
To be added. The Definition Tooltip has its own code, which is not documented yet.
| Setting | Effect |
|---|---|
data-tooltip="Label" | The text. Plain text only, one to three words. |
data-tooltip-position="bottom" | Below the element. Default is above (top). Use Bottom in toolbars (room below), Top in table rows (room above). The flip still applies. |
--tooltip-safe-top on :root | Height in px of a sticky header. Room above then counts from below the header, so a tooltip is flipped below instead of landing on it. Set it from the breakpoint where the header sticks. |
--tooltip-z on :root | z-index of tooltips in markup (.tooltip-wrap), default 300. Set it below a sticky header's z-index. The global tooltip is in the top layer and does not use it. |
| Class | Use |
|---|---|
tooltip-wrap | The wrapper around the trigger and the tooltip. It is the anchor of an automatic tooltip. |
tooltip | The tooltip. Always combined with one type class. |
tooltip--top, tooltip--bottom | Above or below the trigger, centered. Automatic. |
tooltip--top-start, --top-end, --bottom-start, --bottom-end, --left, --right, --left-start, --right-start | The other placement types. Always manual. |
tooltip--body | No beak, no placement. |
tooltip--lg | Large size. |
tooltip--manual | Keeps a Top or Bottom tooltip fixed and centered. |
tooltip--flip, tooltip--align-start, tooltip--align-end | Added by tooltip.js to an open tooltip. Never write them yourself. |
:focus-visible); Esc hides it. On touch it shows on tap and hides on the next tap elsewhere.tooltip.js a markup tooltip stays on its declared side, and a data-tooltip shows nothing.transform, filter or contain on an ancestor makes a markup tooltip's fixed position relative to that ancestor. The global tooltip is not affected. Use tooltip--manual if you must keep a markup tooltip there..row-tooltip, a local .tooltip block), keep the data-tooltip attributes, and add data-tooltip-position="bottom" where the old one opened below.| Topic | Rule |
|---|---|
| Positioning context | Automatic tooltips are position: fixed, so a container with overflow does not clip them. A transform, filter or contain on an ancestor makes fixed relative to that ancestor: use tooltip--manual there. |
| Own positioning script | A page must not position a tooltip with a script of its own (for example inline left): the script and the automatic alignment would fight over the position. Use data-tooltip, or tooltip--manual if a fixed tooltip is really needed. |
| Browser support | Automatic alignment uses CSS anchor positioning. Without support the tooltip stays centered, as in manual mode. |
The component is one CSS file and one script, shared by every page. Link them, never copy them.