Tooltip
Tooltips show supplementary text on hover or focus, such as icon button labels, truncated text, or field hints.
Try it
Usage
Wrap the trigger element and pass content with the tooltip text. Adjust placement and delay for positioning.
import { RuiTooltip } from '@ecopages/radiant-ui/tooltip';
import { RuiButton } from '@ecopages/radiant-ui/button';
<RuiTooltip content="Download report" placement="top" delay={200}>
<RuiButton variant="ghost" aria-label="Download">↓</RuiButton>
</RuiTooltip>Custom markup
<rui-tooltip> coordinates any light-DOM tree that matches its query contract. The
RuiTooltip helper stamps these targets; it is not required.
import '@ecopages/radiant-ui/tooltip';
<rui-tooltip content="Download report" placement="top">
<span class="rui-tooltip">
<span class="rui-tooltip__trigger" data-ref="trigger">
<button type="button" aria-label="Download">↓</button>
</span>
<span data-ref="tooltip" class="rui-tooltip__content rui-floating" role="tooltip" hidden>
Download report
</span>
</span>
</rui-tooltip>;The host queries [data-ref="trigger"] for focus events and [data-ref="tooltip"] for the surface.
Do not set aria-describedby on the trigger — the host wires it.
Supplementary information only
Tooltips should repeat or clarify visible labels, not introduce essential information available nowhere else.
Theming
The tooltip surface maps to semantic surface roles, never Tailwind palette steps. Override --rui-tooltip-* on rui-tooltip.
| Part | Default | Override |
|---|---|---|
| Fill / text | --on-background / --background (inverted) | --rui-tooltip-surface, --rui-tooltip-color |
| Radius / shadow | --radius-container, --shadow-overlay | --rui-tooltip-radius, --rui-tooltip-shadow |
| Padding / max width | --space-2 / --space-1, 20rem | --rui-tooltip-padding-x, --rui-tooltip-padding-y, --rui-tooltip-max-width |
| Z-order | overlay | theme z-index |
rui-tooltip {
--rui-tooltip-max-width: 16rem;
}Accessibility
- Tooltips appear on keyboard focus as well as hover.
- Do not put interactive content inside tooltips, use a popover instead.
- Icon-only buttons should have
aria-label; the tooltip provides redundant confirmation.
API
RuiTooltip is a custom element (<rui-tooltip>) that shows a role="tooltip" surface on hover or focus of its composed trigger, referenced via aria-describedby.
Attributes (<rui-tooltip>)
| Attribute | Type | Default | Description |
|---|---|---|---|
content | string | '' | Accessible description shown in the tooltip. |
placement | RuiPlacement | top | Placement relative to the anchor. |
delay | number | 200 | Show delay in ms (0 shows immediately). |
Light-DOM contract
| Target | Required | Host writes | Author owns |
|---|---|---|---|
[data-ref="trigger"] | yes | — | trigger wrapper; focus bridge |
[data-ref="tooltip"] | yes | id, hidden, position | tooltip text / content |
| focusable anchor | per trigger | aria-describedby | the control inside [data-ref="trigger"] |
Do not set id, hidden, or aria-describedby on the anchor. Nested hosts: none.
View helpers
| Component | Target stamped | Notes |
|---|---|---|
RuiTooltip | [data-ref="trigger"], [data-ref="tooltip"] | content prop mirrors tooltip text. children are the trigger. |
CSS classes
Public BEM classes (documented via @cssclass):
| Class | Description |
|---|---|
.rui-tooltip | Root wrapper. |
.rui-tooltip__trigger | Host wrapper for the composed trigger. |
.rui-tooltip__content | Tooltip surface (role="tooltip"); on-background fill. |
Theme roles
| Part | CSS variables consumed |
|---|---|
| Content | --on-background, --background, --shadow-overlay, --radius-container |
| Z-order | --z-overlay |