Tooltip
Tooltips display a short text label for an element when the user hovers, focuses, or long-presses it.
Usage
forge-tooltip anchors a short text label to another element via anchor (an id reference), and reveals it through triggerType — hover (the default), focus, or longpress — plus placement and flip for positioning. Reserve it for a word or short phrase clarifying an element’s purpose — it’s essential for an icon button with no visible label. For anything longer than a few words, use an inline message or dialog instead of overloading a tooltip.
Rules
Basic usage
Set anchor to the id of the element the tooltip describes.
Or place the tooltip as a child of the element it describes, such as inside a forge-icon-button. It anchors to its parent without needing an anchor id. Make it the first child: a tooltip with a previous sibling anchors to that sibling instead (see Anchor gotchas below).
<forge-icon-button aria-label="Delete">
<forge-tooltip>Delete</forge-tooltip>
<forge-icon name="delete"></forge-icon>
</forge-icon-button>A tooltip anchored to a button by id.
<forge-button id="my-button" variant="raised">
Hover me
</forge-button>
<forge-tooltip anchor="my-button" aria-hidden>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</forge-tooltip>Placement
Set placement to move the tooltip above its anchor instead of the default right.
A tooltip placed above its anchor instead of the default right.
<forge-button id="tooltip-placement-anchor" variant="raised">
Hover me
</forge-button>
<forge-tooltip anchor="tooltip-placement-anchor" placement="top">
Placed above
</forge-tooltip>Trigger type
Set triggerType to focus to open the tooltip on focus instead of hover — pair the two so the tooltip is reachable without a mouse.
A tooltip that opens on focus instead of hover.
<forge-button id="tooltip-trigger-anchor" variant="raised">
Focus me
</forge-button>
<forge-tooltip anchor="tooltip-trigger-anchor" trigger-type="focus">
Opens on focus
</forge-tooltip>Type
Set type to presentation (the default), label, or description to control the tooltip’s accessibility association with its anchor.
A presentation tooltip (default) carries no accessibility association with its anchor.
<forge-button id="tooltip-type-anchor" variant="raised">
Hover me
</forge-button>
<forge-tooltip anchor="tooltip-type-anchor" type="presentation">
Visual only
</forge-tooltip>Anchor gotchas
If the anchor element is placed in a slot (e.g. an icon button slotted into an app bar), the tooltip needs the same slot attribute — otherwise it may not render at all.
<forge-app-bar>
<forge-icon-button slot="end" id="my-button">
<forge-icon name="forge_logo"></forge-icon>
</forge-icon-button>
<forge-tooltip slot="end" type="label" anchor="my-button">This is a tooltip</forge-tooltip>
</forge-app-bar>Without an explicit anchor, the tooltip resolves its target in this order: the element matching anchor’s id, then anchorElement if set, then its previous DOM sibling, then its parent element. That’s unpredictable in a dynamic context — a list of items, or anything rendered asynchronously — so set anchor or anchorElement explicitly whenever the tooltip isn’t a fixed, static sibling of what it describes.
Despite rendering in the browser’s top layer, the tooltip element itself still lives inline in the DOM, which means it can inherit CSS custom properties from its ancestors and pick up unintended style bleed. If that happens, set anchor or anchorElement to move the tooltip to a different point in the DOM, detached from the ancestor setting the variable.
Tooltips display information related to an element when the user focuses or hovers over an anchor element. Use tooltips to provide additional context or information about elements that may not be immediately apparent.
import "@tylertech/forge/tooltip";| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
open | open | boolean | false | Whether or not the tooltip is open. |
type | type | TooltipType | "presentation" | The type of tooltip. Valid values are `presentation` (default), `label`, and `description`. |
anchor | anchor | string | — | The id of the element that the tooltip is anchored to. |
anchorElement | — | HTMLElement | null | — | |
target | — | string | — | |
placement | placement | TooltipPlacement | "right" | The placement of the tooltip relative to the anchor element. |
position | — | `${TooltipPlacement}` | — | |
delay | delay | number | 500 | The delay in milliseconds before the tooltip is shown. |
offset | offset | number | 4 | The offset in pixels between the tooltip and the anchor element. |
flip | flip | OverlayFlipState | "auto" | How the tooltip should place itself if there is not enough space at the desired placement. |
boundary | boundary | string | null | — | The id of the element that the tooltip should be constrained to. |
boundaryElement | — | HTMLElement | null | — | The element that the tooltip should be constrained to. |
fallbackPlacements | fallback-placements | PositionPlacement[] | — | The fallback placements of the tooltip relative to the anchor element. |
triggerType | trigger-type | TooltipTriggerType | TooltipTriggerType[] | "hover" | The trigger type(s) that will open the tooltip. Valid values are `hover` (default), `longpress`, and `focus`. |
| Name | Description |
|---|---|
(default) | The content to display in the tooltip. |
| Name | Description |
|---|---|
::part(surface) | The tooltip surface. |
::part(arrow) | The tooltip arrow. |
::part(overlay) | The overlay surface. |
| Name | Description |
|---|---|
--forge-tooltip-background | The background color of the tooltip surface. |
--forge-tooltip-color | The text color of the tooltip surface. |
--forge-tooltip-shape | The shape of the tooltip surface. |
--forge-tooltip-padding | The padding of the tooltip surface. |
--forge-tooltip-padding-block | The block padding of the tooltip surface. |
--forge-tooltip-padding-inline | The inline padding of the tooltip surface. |
--forge-tooltip-max-width | The maximum width of the tooltip surface. |
--forge-tooltip-elevation | The elevation of the tooltip surface. |
--forge-tooltip-border-width | The border width of the tooltip surface. |
--forge-tooltip-border-style | The border style of the tooltip surface. |
--forge-tooltip-border-color | The border color of the tooltip surface. |
--forge-tooltip-animation-timing | The animation timing function of the tooltip surface. |
--forge-tooltip-animation-duration | The animation duration of the tooltip surface. |
--forge-tooltip-animation-offset | The animation offset of the tooltip surface. |
--forge-tooltip-arrow-size | The size of the tooltip arrow. |
--forge-tooltip-arrow-height | The height of the tooltip arrow. |
--forge-tooltip-arrow-width | The width of the tooltip arrow. |
--forge-tooltip-arrow-shape | The shape of the tooltip arrow. |
--forge-tooltip-arrow-clip-path | The clip path of the tooltip arrow. |
--forge-tooltip-arrow-rotation | The rotation of the tooltip arrow. |
--forge-tooltip-arrow-top-rotation | The rotation of the tooltip arrow when the tooltip is placed on top. |
--forge-tooltip-arrow-right-rotation | The rotation of the tooltip arrow when the tooltip is placed on the right. |
--forge-tooltip-arrow-bottom-rotation | The rotation of the tooltip arrow when the tooltip is placed on the bottom. |
--forge-tooltip-arrow-left-rotation | The rotation of the tooltip arrow when the tooltip is placed on the left. |
Contrast
Verify there’s sufficient contrast between the tooltip’s foreground text and background to meet WCAG requirements.
No interactive content
A tooltip shouldn’t contain interactive content — a user can’t reliably move a pointer or focus into a tooltip that disappears on blur or hover-out.
Labeling
Set type to label or description to have the tooltip wire up aria-labelledby or aria-describedby on its anchor element automatically. The default, presentation, is purely visual and carries no accessible relationship to the anchor.