Tooltip Documentation has not yet been reviewed by a human.
Use Tooltip for supplementary explanations and the full text of clipped labels. Place it inside the element it describes. It takes no space in that element’s layout. Keep essential instructions and actions available without a tooltip.
Change the Tooltip props or edit its content, then hover or focus the button. Use the CSS placement options to try the anchor near a viewport edge.
Examples
Hover Status for a text explanation, focus the underlined button with Tab, follow the cursor, or enter the interactive bubble to use its link.
<div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}> <span style={{ cursor: 'help', display: 'inline-flex', alignItems: 'center', gap: '4px' }}> <span>Status</span> <Icon shape="info" size={16} style={{ color: 'var(--text-5)' }} /> <Tooltip placement="top">Last checked 2 minutes ago</Tooltip> </span> <Button priority="tertiary" underline="dashed" label="Focus me with the keyboard"> <Tooltip delay={50}>Shows on focus, dismiss with Esc</Tooltip> </Button> <Button label="Follow the cursor"> <Tooltip follow>Tracks the pointer, fades as you leave</Tooltip> </Button> <Button label="Interact"> <Tooltip interactive placement="top"> See the <a href="/install/">full guide</a> for details </Tooltip> </Button></div>Hover and keyboard focus
Hover the button or reach it with Tab to show its explanation after a delay. Escape dismisses it. Leaving the anchor, moving focus away, or scrolling also closes it. On touch screens, hold the anchor for 500ms; a quick tap does not open it. After release, a touch tooltip remains for 1.5 seconds.
Give the trigger an accessible name independently. Put explanations that should
be available before opening on the trigger with authored ARIA. Here,
aria-description supplies the short description in both open and closed states.
<Button label="Publish" aria-description="Makes the draft public"> <Tooltip id="publish-tooltip" delay={50}>Makes the draft public</Tooltip></Button>Placement
Choose top or left to prefer another side. Tooltip flips when that side has
insufficient room and keeps the bubble within the viewport.
<Button label="Below"><Tooltip>Below the anchor</Tooltip></Button><Button label="Above"><Tooltip placement="top">Above the anchor</Tooltip></Button><Button label="Beside"><Tooltip placement="left">Beside the anchor</Tooltip></Button>Follow the cursor
Use follow for explanations attached to a larger pointer target. The bubble
tracks the cursor and fades with distance as the pointer leaves. Moving between
two follow anchors skips the next delay while the previous tooltip is open or
within its 300ms grace period. Pinned tooltips keep their configured delay.
Keyboard and touch openings stay anchored to the target.
<Button label="First"><Tooltip follow>First explanation</Tooltip></Button><Button label="Second"><Tooltip follow>Second explanation</Tooltip></Button>Interactive content
Pass interactive to enter the bubble with the pointer or keyboard and use its
content. It stays pinned even when follow is present. Move from the trigger to
the link, or focus the trigger and press Tab. Escape dismisses the bubble.
This option preserves Tooltip’s existing tooltip semantics. The ARIA tooltip pattern describes nonfocusable content; use Menu or Dialog for essential actions that need an explicit trigger and popup semantics.
<Button label="Help" aria-description="Read the installation guide for setup details"> <Tooltip id="help-tooltip" interactive placement="top"> Read the <a href="/install/">installation guide</a>. </Tooltip></Button>Show only when truncated
Use truncatedOnly when the explanation repeats a label. A label that fits does
not open a bubble. Hover both labels to compare a clipped target with one that
fits.
<div style={{ display: 'flex', gap: '28px', alignItems: 'flex-start', flexWrap: 'wrap' }}> <span style={{ display: 'inline-block', maxWidth: '130px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', cursor: 'help' }}> A long label that gets truncated <Tooltip truncatedOnly>A long label that gets truncated</Tooltip> </span> <span style={{ display: 'inline-block', cursor: 'help' }}> Short label <Tooltip truncatedOnly>Short label</Tooltip> </span></div>Text with truncate already creates an automatic tooltip for clipped,
non-expandable content.
<Text truncate style={{ maxWidth: '160px' }}> A long release title that does not fit in this space</Text><Text truncate>Short title</Text>Nest your own Tooltip inside Text to replace its automatic explanation. An empty explicit Tooltip suppresses the automatic one.
<Text truncate style={{ maxWidth: '160px' }}> A long release title with a custom explanation <Tooltip>This release includes keyboard navigation improvements.</Tooltip></Text>Adjacent and nested tooltips
One tooltip is open per document. A tooltip on a nested anchor takes precedence while that anchor is active. Returning to the outer anchor makes its explanation available again.
<div style={{ display: 'flex', gap: '40px', alignItems: 'flex-start', flexWrap: 'wrap' }}> <div style={{ display: 'flex', gap: '12px' }}> <Button label="First"><Tooltip follow>First tooltip</Tooltip></Button> <Button label="Second"><Tooltip follow>Second tooltip</Tooltip></Button> </div> <div tabIndex={0} aria-label="Outer box" style={{ padding: '20px', border: '1px dashed var(--border-4)', borderRadius: '6px', cursor: 'help' }}> <span>Outer box</span> <Tooltip follow>Outer tooltip</Tooltip> <div style={{ marginTop: '12px' }}> <Button label="Inner button"><Tooltip follow>Inner tooltip</Tooltip></Button> </div> </div></div>Content and shape
Content can include text, icons, and markup. An empty or whitespace-only tooltip
does not open. Clearing an open tooltip’s content closes it; subsequent content
is available on the next interaction. Use round for a softer shape.
<Button label="Release status"> <Tooltip round><strong>Healthy</strong> · Checked two minutes ago</Tooltip></Button><Button icon="info" aria-label="Action details"> <Tooltip placement="top"><strong>Heads up</strong> · This action cannot be undone</Tooltip></Button><Button label="No explanation"><Tooltip>{''}</Tooltip></Button> Component props
| Prop | Type | Default | Description |
|---|---|---|---|
| children? | ReactNode | — | Supplementary text or markup. Content stays in light DOM for application CSS. |
| delay? | number | 300 | Wait in milliseconds after hover or keyboard focus. Use 50 for a short delay. |
| placement? | topbottomleft | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
| round? | booleannumberstring | — | Round the bubble to a 20px radius (matching a round menu). Pass a number
(px) or a CSS length string for a custom radius. |
| follow? | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is
pinned (anchored beneath the target) by default; pass follow for the
cursor-tracking behavior, which fades by distance as the cursor leaves. |
| interactive? | boolean | — | Keep content available while the pointer or keyboard focus is inside it.
Enables pointer events and pins the bubble even with follow. Essential
actions belong in a Menu or Dialog with an explicit trigger. |
| truncatedOnly? | boolean | — | Only show when the target is actually truncated (its text overflows and is
ellipsized); a label that fits gets no tooltip. The check is a UI-thread
layout read, re-measured on each show. By default it measures every Anta
ellipsizing label part inside the anchor, then the anchor itself —
override with truncatedSelector. |
| truncatedSelector? | string | — | CSS selector (resolved within the anchor) for the element or elements
whose overflow decides whether a truncatedOnly tooltip shows. |
Inherited props (className, id, slot, style, tabIndex, title)
| Prop | Type | Default | Description |
|---|---|---|---|
| className? | string | — | CSS class on the component's root element (merged with the component's own
classes). Use it directly for layout and positioning — grid/flex placement,
margins, alignment — rather than wrapping the component in a <div>/<span>. |
| id? | string | — | HTML id attribute. |
| slot? | string | — | Assigns the element to a named <slot> of a parent web component (e.g.
slot="header" inside a <Dialog>, slot="footer" inside a <Dialog>). |
| style? | CSSProperties | — | Inline styles on the component's root element. Set layout/positioning here
(or via className) directly on the component instead of adding a wrapper. |
| tabIndex? | number | — | Tab order. Set to -1 to skip the element when tabbing. |
| title? | string | — | HTML title attribute — native browser tooltip on hover. |
Plus every standard DOM event handler (onClick,
onFocus, onKeyDown, …) and any
data-* or aria-* attribute — forwarded as-is to
the underlying <a-*> element.
truncatedOnly measures the anchor’s reported truncation or its a-tab-label,
a-button-label, and a-step-hint regions. truncatedSelector selects a different
measurement target. Measurements are refreshed when opening.
A custom numeric or length round prop emits an inline CSS variable. If your CSP
blocks style attributes, use external ::part(bubble) CSS for a custom radius.
Web Component
Place a-tooltip directly inside its anchor. The author owns markup, styles,
accessible names, and descriptions. Tooltip does not add attributes
to its anchor or rewrite the supplied content.
<a-button role="button" tabindex="0" aria-label="Publish" aria-description="Makes the draft public"> <a-button-label>Publish</a-button-label> <a-tooltip id="raw-publish-tooltip">Makes the draft public</a-tooltip></a-button>Referencing the Tooltip host with aria-describedby does not provide a reliable
description while its internal popover is hidden. Use an authored
aria-description, or reference separate application-owned descriptive content
that remains available to assistive technology.
Raw attributes include delay, placement, round, follow, interactive,
truncated-only, and truncated-selector. Boolean attributes use presence.
An anchor can implement getAnchorRect(): DOMRect to advertise a smaller
positioning region; Input reports its field instead of its label and hint.
Default styles load from the external component stylesheet. Under CSP, allow that same-origin stylesheet and the browser entry. Runtime positioning updates only Tooltip’s owned shadow elements. Input and Menu also load their defaults from external CSS. Custom values serialized into HTML style attributes remain subject to the CSP guidance.
Reduced motion disables both fades. Older supported browsers can omit parts of the native popover transition while retaining the content and interaction.
Styling
Style the visible surface with ::part(bubble). Supplied content remains in light
DOM, so application selectors can style its text. ::part(container) reaches
the outer popover and its opening/closing transition. Keep its positioning and
pointer behavior intact when changing appearance.
The classes below identify this demonstration; use your own selectors.
a-tooltip.custom-tooltip::part(bubble) { background: #1a161d; border-radius: 10px; padding: 8px 12px; box-shadow: 0 4px 18px color-mix(in oklch, black 35%, transparent); backdrop-filter: none;}.custom-tooltip-text { color: #fff; font-size: 15px; font-weight: 600; letter-spacing: 0.01em;}