Tooltip
A lightweight floating label that appears on hover, focus, or click. Automatically flips placement when near viewport edges and dismisses on Escape.
Placement
<ore-tooltip content="Tooltip on top" placement="top">
<ore-button size="sm">Top</ore-button>
</ore-tooltip>
<ore-tooltip content="Tooltip on right" placement="right">
<ore-button size="sm">Right</ore-button>
</ore-tooltip>
<ore-tooltip content="Tooltip on bottom" placement="bottom">
<ore-button size="sm">Bottom</ore-button>
</ore-tooltip>
<ore-tooltip content="Tooltip on left" placement="left">
<ore-button size="sm">Left</ore-button>
</ore-tooltip>Trigger Modes
Use the trigger attribute to control when the tooltip appears. Multiple triggers can be combined with commas (e.g. "hover,focus"). When trigger includes focus, the tooltip is automatically wired as a programmatic description (aria-describedby) for the focused element, which benefits screen reader users. A tooltip with the click trigger also closes when a pointer press starts outside its trigger and bubble; hover/focus-only tooltips do not use outside-pointer dismissal.
For explanations that also need tap activation, use trigger="hover,focus,click". A touch press that focuses the trigger opens the tooltip once and keeps it open; a second tap closes it. Touch pointer entry and exit do not act as hover. Changing trigger after mounting updates its listeners and cancels pending show/hide delays without replacing the element.
<ore-tooltip content="Hover trigger" trigger="hover">
<ore-button size="sm" variant="flat">Hover me</ore-button>
</ore-tooltip>
<ore-tooltip content="Focus trigger (Tab to this button)" trigger="focus">
<ore-button size="sm" variant="flat">Focus me</ore-button>
</ore-tooltip>
<ore-tooltip content="Click trigger" trigger="click">
<ore-button size="sm" variant="flat">Click me</ore-button>
</ore-tooltip>
<ore-tooltip content="Hover or focus" trigger="hover,focus">
<ore-button size="sm" variant="flat">Hover / Focus</ore-button>
</ore-tooltip>Variants
<ore-tooltip content="Dark tooltip (default)">
<ore-button size="sm">Dark</ore-button>
</ore-tooltip>
<ore-tooltip content="Light tooltip" variant="light">
<ore-button size="sm">Light</ore-button>
</ore-tooltip>Prefer variant="light" on dark backgrounds.
Sizes
<ore-tooltip content="Small tooltip" size="sm">
<ore-button size="sm">Small</ore-button>
</ore-tooltip>
<ore-tooltip content="Medium tooltip (default)" size="md">
<ore-button size="sm">Medium</ore-button>
</ore-tooltip>
<ore-tooltip content="Large tooltip" size="lg">
<ore-button size="sm">Large</ore-button>
</ore-tooltip>Show and Hide Delay
An unset delay opens on a trigger-aware dwell: 300ms on hover (so sweeping a pointer across a toolbar fires only the tooltip you rested on), and immediate on focus or click (both are deliberate). An unset close-delay hides after a 100ms grace on pointer leave (absorbing jitter across the trigger edge), and immediately on focus out.
Set delay or close-delay explicitly to override; delay="0" forces an immediate open on every trigger.
Shared Hover Warm-Up
The nearest ancestor with data-tooltip-group or role="toolbar" scopes hover warm-up. After one tooltip opens by hover, its siblings open immediately while a tooltip is open and for 500ms after the last closes. The first hover after that window uses the normal 300ms dwell again. Ungrouped tooltips and separate groups remain independent; an explicit delay always wins. Focus and click remain immediate when delay is unset.
<div data-tooltip-group>
<ore-tooltip content="Undo last change"><ore-button>Undo</ore-button></ore-tooltip>
<ore-tooltip content="Redo last change"><ore-button>Redo</ore-button></ore-tooltip>
</div><ore-tooltip content="Appears after 600ms" delay="600">
<ore-button size="sm" variant="outline">Delayed</ore-button>
</ore-tooltip>Rich Content via Slot
For complex tooltip content, use the content named slot. Keep tooltip text short: one sentence or a keyboard shortcut label. Do not add interactive elements (buttons, links) inside the tooltip bubble; tooltips are not focusable.
<ore-tooltip>
<ore-button size="sm">Keyboard shortcut</ore-button>
<span slot="content">
Paste <kbd style="background:rgba(255,255,255,.15);border-radius:3px;padding:1px 4px;">⌘V</kbd>
</span>
</ore-tooltip>Disabled Tooltips
Set disabled to suppress the tooltip entirely.
<ore-tooltip content="This won't show" disabled>
<ore-button>No tooltip</ore-button>
</ore-tooltip>Controlled Open State
Set open to control visibility. When a click-enabled tooltip requests dismissal, update open from the open-change event. Use default-open only to initialize an uncontrolled tooltip.
<ore-tooltip id="save-tip" content="Save changes" trigger="click">
<ore-button>Save</ore-button>
</ore-tooltip>
<script type="module">
const tooltip = document.getElementById('save-tip');
tooltip.open = true;
tooltip.addEventListener('open-change', (e) => {
tooltip.open = e.detail.open;
console.log('tooltip open:', tooltip.open, e.detail.reason);
});
</script>API Reference
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
content | string | '' | Tooltip text |
placement | 'top' | 'bottom' | 'left' | 'right' | 'top' | Preferred placement (auto-flips near viewport edges) |
trigger | string | 'hover,focus' | Trigger mode(s), comma-separated |
delay | number | 300 hover / immediate focus·click | Show delay in ms: 300 on hover, immediate on focus/click when unset |
close-delay | number | 100 pointer-leave / immediate focus-out | Hide delay in ms: 100 on pointer leave, immediate on focus out when unset |
open | boolean | N/A | Controlled open state; when set, trigger events are ignored |
default-open | boolean | false | Initial visibility when open is not provided |
variant | 'dark' | 'light' | N/A | Visual style (dark appearance is the unset default) |
size | 'sm' | 'md' | 'lg' | N/A | Tooltip bubble size (medium appearance is the unset default) |
disabled | boolean | false | Disable the tooltip entirely |
Slots
| Slot | Description |
|---|---|
| (default) | The trigger element the tooltip is anchored to |
content | Rich tooltip content (overrides the content attribute) |
Events
| Event | Detail | Description |
|---|---|---|
open-change | { open: boolean, reason: string } | Emitted whenever the tooltip opens or closes |
CSS Custom Properties
| Property | Description | Default |
|---|---|---|
--tooltip-max-width | Max width of the bubble | 18rem |
Accessibility
The tooltip component follows WAI-ARIA best practices. The tooltip bubble has role="tooltip", and the trigger element is automatically augmented with aria-describedby pointing to the tooltip when the focus trigger is active. Pressing Escape while a tooltip is visible dismisses it.
Avoid using tooltips to hold essential information: if the user must see it to act, put it in helper text or an alert instead. Use trigger="focus" (or "hover,focus") for form field hints so keyboard-only users see them.