Tooltip
A simple text prompt bubble triggered on hover or keyboard focus.
Basic usage
Trigger on hover
Placement
Four directions
When space is insufficient, the tooltip automatically flips along the main axis and avoids the viewport edges.
Arrow
By default an arrow pointing at the trigger element's edge is shown; arrow="false" hides the arrow; arrow-point-at-center makes the arrow point at the trigger element's center (when the panel is shifted by viewport-edge avoidance, the arrow still points at the anchor center).
Arrow visibility and pointing
arrow-position="merge" merges the arrow with the panel corner into a right triangle (only for *-start / *-end placements).
Arrow merge mode
Viewport auto adjust
By default the tooltip automatically flips along the main axis and avoids the viewport edges when space is insufficient; auto-adjust-overflow="false" disables the auto adjust so the panel keeps the declared placement (it may overflow the viewport).
Auto adjust disabled
Focus trigger
Trigger on keyboard focus
Controlled display
The open attribute is controlled: an external button can set/remove open to show/hide the tooltip (hover/focus triggers still apply in addition).
Controlled display (open attribute)
Long text
Long text and max width
Virtual trigger
Virtual mode (virtual) does not bind to a host trigger element: open is fully controlled externally, and the position is set by virtual-anchor (an anchor element selector) or virtual-x / virtual-y (viewport coordinates). placement still applies. It suits scenarios where a normal trigger element is impossible, such as chart points or floating hints during drag.
Virtual anchor follow (chart points)
Hover any point to see the hint (the tooltip is anchored to that point).
Coordinate follow (mouse move)
Triggers
The trigger attribute supports space-separated multi-selection: hover / focus / click / contextmenu / touch (long press) / manual (fully controlled). Defaults to hover focus.
Click trigger
Context menu trigger
Manual trigger
Show / hide delay
open-delay / close-delay control the delay (ms) before showing/hiding on hover, avoiding accidental triggers when moving across quickly.
Open and close delays
When moving quickly across multiple triggers, skip-delay-duration (default 300ms) makes the next tooltip skip its open-delay and appear immediately, keeping the interaction responsive.
Delay group (skip-delay-duration)
On touch devices, trigger="touch" shows on long press (touch-delay controls the hold duration, default 500ms).
Touch long-press trigger
Rich content
The content attribute shows plain text; for rich content (links, icons, multiple lines) use the slot="content" slot. The slot takes precedence over the attribute text.
Rich content slot
Keyboard accessibility
While open, pressing Esc closes the tooltip and restores focus to the trigger; while open, the trigger is linked to the popup via aria-describedby (readable by screen readers).
Esc close + aria-describedby
trigger-keys lets you specify keys (space-separated) that open the tooltip when focused, e.g. trigger-keys="F1".
trigger-keys open
Max width
The default max width is 240px (opened via the --oas-tooltip-max-width token); the max-width attribute overrides it (number or CSS length).
Custom max width
Disabled
With disabled, the tooltip never shows (neither hover nor a controlled open).
Disabled
Hoverable popup
interactive keeps the popup open while hovering it (links inside stay reachable).
Interactive popup
Offset and collision
offset controls the main-axis distance (default 8px), skidding the cross-axis offset, and collision-padding the viewport-edge avoidance margin (default 4px).
offset / skidding
collision-padding
Color variants
The color attribute supports semantic colors (primary / success / warning / danger), the 11 preset names (e.g. magenta, blue), or any CSS color. All of them go through tokens (with dark variants).
Color variants
Mount point
append-to mounts the popup into the given container (body or a CSS selector), escaping clipping contexts such as an overflow: hidden ancestor.
append-to body
Auto close
auto-close (ms) closes the tooltip automatically after it opens — useful for onboarding hints.
Auto close
Fresh content
fresh is enabled by default: content changes are synced immediately even while closed (reopening always shows the latest). fresh="false" freezes the content while closed.
Fresh content sync
Edge cases
Empty content
API
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
append-to | Popup mount point: body or a CSS selector. Moves the popup into an isolated shadow inside the target container (styles stay scoped), escaping clipping contexts such as overflow: hidden / transform; while mounted, ::part(tip) cannot pierce from the host — customize via CSS variables or class selectors | string | — |
arrow | Whether to show the arrow (default true; arrow="false" hides it, the element and ::part(arrow) are kept) | string | true |
arrow-point-at-center | Make the arrow point at the trigger element's center (default points at the trigger's edge; the arrow still points at the anchor center when the panel is shifted by viewport-edge avoidance) | boolean | — |
arrow-position | Arrow shape: center (default, arrow centered on the panel edge) / merge (only for *-start/*-end placements; a right triangle merges flush with the panel corner — legs collinear with the panel edges, tip pointing orthogonally toward the anchor) | string | center |
auto-adjust-overflow | Viewport-edge auto flip and avoidance (default true; "false" disables it, keeping the declared placement, which may overflow the viewport) | string | true |
auto-close | Auto-close after opening (ms); 0 or absent disables it | — | — |
close-delay | Hide delay (ms, default 0): close after mouseleave/focusout | — | — |
collision-padding | Viewport-edge avoidance margin (px, default 4): the distance kept from the edge when the popup is clamped | — | — |
color | Color variant: semantic primary/success/warning/danger, one of the 11 preset names (e.g. magenta, blue), or any CSS color. All go through tokens (with dark variants); the arrow background follows | string | — |
content | Tooltip content text (the slot="content" rich content takes precedence when present) | string | — |
disabled | Disabled: the tooltip never shows (neither hover nor a controlled open) | boolean | — |
fresh | Content freshness (default true): content changes are synced immediately even while closed; "false" freezes the content while closed, updating on next open | string | true |
interactive | Hoverable popup: moving the mouse into the popup keeps it open (pointer-events: auto), links inside stay reachable | boolean | — |
max-width | Popup max width (number in px or CSS length; defaults to the --oas-tooltip-max-width token, 240px) | string | — |
offset | Main-axis distance (px, default 8): the gap between the popup and the anchor along the main axis | — | — |
open | Controlled display (boolean attribute; shows when present) | boolean | — |
open-delay | Show delay (ms, default 0): open after mouseenter/focusin; skipped when skip-delay-duration hits | — | — |
placement | Popup placement (12 directions: top/bottom/left/right × start/center/end) | Placement | top |
skidding | Cross-axis offset (px, default 0): top/bottom placements shift horizontally (positive right, negative left); left/right placements shift vertically (positive down, negative up) | — | — |
skip-delay-duration | Global delay-group threshold (ms, default 300): when a tooltip closes, the next one opened within this window skips its open-delay and shows immediately (responsive for consecutive hovers); "0" disables it | — | — |
touch-delay | Touch long-press trigger duration (ms, default 500): with touch in trigger, pointerdown held to the threshold opens; releasing/moving out earlier cancels | — | — |
trigger | Trigger modes (space-separated multi-select): hover / focus / click / contextmenu / touch / manual, default hover focus; manual is fully controlled | string | hover focus |
trigger-keys | Specified keys (space-separated, e.g. F1): pressing one while the trigger is focused opens the tooltip | string | — |
virtual | Virtual trigger mode: not bound to a host trigger element; open is fully controlled externally and the position is set by virtual-anchor or virtual-x/virtual-y (for chart points, floating hints during drag) | boolean | — |
virtual-anchor | Anchor element selector (e.g. #chart-point-1); the tooltip is positioned by that element's rect. Mutually exclusive with virtual-x/virtual-y (coordinates take precedence) | — | — |
virtual-x | Virtual anchor viewport X coordinate (px, e.g. mouse clientX); position by coordinates when set together with virtual-y | — | — |
virtual-y | Virtual anchor viewport Y coordinate (px, e.g. mouse clientY); position by coordinates when set together with virtual-x | — | — |
Events
| Event | Description |
|---|---|
oas-open-change | Fired when the open state changes (show/hide), detail: { open } |
Slots
| Name | Description |
|---|---|
| default | Trigger element (hover/focus trigger); optional in virtual mode |
content | Rich content (takes precedence over the content attribute text when present) |
oas-open-change: fired when the open state changes (show/hide), detail: { open }. Shown/hidden on hover or focus; role="tooltip", the popup uses pointer-events: none so it never blocks interactions.