Tooltip
A short description that appears when a button is hovered or focused.
Tooltip follows the Tooltip WAI-ARIA design pattern.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Tooltip } from '@leve-ui/tooltip';
import { LuUndo2 } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
// The tooltip describes the button (aria-describedby); the button keeps its own label
return (
<Tooltip.Root>
<Tooltip.Trigger aria-label="Undo" class="tooltip-default-trigger">
<LuUndo2 class="tooltip-default-icon" aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content sideOffset={6} class="tooltip-default-content">
Undo the last change (Ctrl+Z)
<Tooltip.Arrow class="tooltip-default-arrow" />
</Tooltip.Content>
</Tooltip.Root>
);
});.tooltip-default-trigger {
display: inline-flex;
padding: 8px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.tooltip-default-trigger:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.tooltip-default-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.tooltip-default-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.tooltip-default-content {
max-width: 240px;
padding: 6px 10px;
border: none;
border-radius: 6px;
background: light-dark(#0f172a, #ffffff);
color: light-dark(#ffffff, #0f172a);
font-family: inherit;
font-size: 13px;
overflow: visible;
}
/* Fade in when it opens */
.tooltip-default-content:popover-open {
transition: opacity 120ms ease;
@starting-style {
opacity: 0;
}
}
/* A small rotated square on the edge facing the Trigger */
.tooltip-default-arrow {
width: 8px;
height: 8px;
background: inherit;
rotate: 45deg;
}
.tooltip-default-arrow[data-side="top"] {
margin-bottom: -4px;
}
.tooltip-default-arrow[data-side="bottom"] {
margin-top: -4px;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/tooltipnpm install @leve-ui/tooltipyarn add @leve-ui/tooltipbun add @leve-ui/tooltippnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Tooltip } from '@leve-ui/tooltip'; // or '@leve-ui/core'
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Content>
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Root>
| Part | Element | Description |
|---|---|---|
Tooltip.Root | <span> | Wraps the parts and holds the open state. An inline element, so it fits in a row of buttons or in text. |
Tooltip.Trigger | <button> | The element that the tooltip describes. Use as to render another element or component. |
Tooltip.Content | <span> | The tooltip, a popover="manual" element in the top layer. A <span> so that it can be placed in a paragraph. |
Tooltip.Arrow | <span> | Optional. An arrow pointing at the Trigger, drawn with CSS. |
Use as to attach a tooltip to another element or component such as a link. A component passed to as must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.
Tooltips are for short, plain text. Do not put links or buttons in them: use Popover for interactive content.
Examples#
Custom Trigger#
Pass an element name or a component (such as Qwik City's <Link>) to as on Tooltip.Trigger.
import { $, component$, type PropsOf, Slot, sync$, useStyles$ } from '@builder.io/qwik';
import { Tooltip } from '@leve-ui/tooltip';
import { LuUndo2 } from '@qwikest/icons/lucide';
import styles from './custom-trigger.css?inline';
// Example of a consumer link component (such as Qwik City's <Link>) that spreads props onto <a>
const ClientLink = component$<PropsOf<'a'>>(({ onClick$, ...props }) => {
const preventDefault$ = sync$((event: MouseEvent) => {
event.preventDefault();
});
return (
<a {...props} onClick$={[preventDefault$, $(() => {}), onClick$]}>
<Slot />
</a>
);
});
export default component$(() => {
useStyles$(styles);
return (
<Tooltip.Root>
<Tooltip.Trigger
as={ClientLink}
href="#undo"
aria-label="Undo"
class="tooltip-custom-trigger"
>
<LuUndo2 class="tooltip-custom-trigger-icon" aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content sideOffset={6} class="tooltip-custom-trigger-content">
Undo the last change (Ctrl+Z)
<Tooltip.Arrow class="tooltip-custom-trigger-arrow" />
</Tooltip.Content>
</Tooltip.Root>
);
});.tooltip-custom-trigger {
display: inline-flex;
padding: 8px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
text-decoration: none;
cursor: pointer;
}
.tooltip-custom-trigger:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.tooltip-custom-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.tooltip-custom-trigger-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.tooltip-custom-trigger-content {
max-width: 240px;
padding: 6px 10px;
border: none;
border-radius: 6px;
background: light-dark(#0f172a, #ffffff);
color: light-dark(#ffffff, #0f172a);
font-family: inherit;
font-size: 13px;
overflow: visible;
}
/* Fade in when it opens */
.tooltip-custom-trigger-content:popover-open {
transition: opacity 120ms ease;
@starting-style {
opacity: 0;
}
}
/* A small rotated square on the edge facing the Trigger */
.tooltip-custom-trigger-arrow {
width: 8px;
height: 8px;
background: inherit;
rotate: 45deg;
}
.tooltip-custom-trigger-arrow[data-side="top"] {
margin-bottom: -4px;
}
.tooltip-custom-trigger-arrow[data-side="bottom"] {
margin-top: -4px;
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { trigger?: string; content?: string } Overrides the element IDs of the parts. |
| defaultOpen | false | boolean Whether the tooltip is shown initially (uncontrolled). |
| bind:open | – | Signal<boolean> A signal with the open state (controlled). |
| onOpenChange$ | – | QRL<(open: boolean) => void> Called when the tooltip is shown or hidden by a user interaction. |
| openDelay | 700 | number The delay in ms before the tooltip opens when the pointer rests on the Trigger. Focus opens it at once. |
| closeDelay | 300 | number The delay in ms before the tooltip closes when the pointer leaves, so that the pointer can move onto it. |
Also accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-tooltip | Always present |
data-state | "open" | "closed" |
Trigger#
| Prop | Default | Type |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-tooltip-trigger | Always present |
data-state | "open" | "closed" |
Content#
| Prop | Default | Type |
|---|---|---|
| side | 'top' | 'top' | 'right' | 'bottom' | 'left' The side of the Trigger to place the tooltip on. It flips when there is no room. |
| align | 'center' | 'start' | 'center' | 'end' The alignment along that side. |
| sideOffset | 0 | number The distance from the Trigger in px. |
| alignOffset | 0 | number The offset along the side in px. |
| avoidCollisions | true | boolean Whether to flip and shift the tooltip to keep it in the viewport. |
| collisionPadding | 0 | number The padding from the viewport edges when avoiding collisions, in px. |
| arrowPadding | 0 | number The padding between the arrow and the corners of the tooltip, in px. |
Also accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-tooltip-content | Always present |
data-state | "open" | "closed" |
data-side | The final side after flipping: "top" | "right" | "bottom" | "left" |
data-align | "start" | "center" | "end" |
| CSS variable | Value |
|---|---|
--leve-tooltip-anchor-width | The width of the Trigger |
--leve-tooltip-anchor-height | The height of the Trigger |
--leve-tooltip-available-width | The width available in the viewport |
--leve-tooltip-available-height | The height available in the viewport |
The Content gets inline position, top and left while it is open. It matches :popover-open while shown; use it with @starting-style to animate it. Set display (for example flex) only on :popover-open: on the Content itself, it would override the browser's display: none of the closed popover.
Arrow#
No props of its own. Accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-tooltip-arrow | Always present |
data-side | The final side of the Content |
Accessibility#
Complies with the Tooltip WAI-ARIA design pattern.
Tooltip.Contentrendersrole="tooltip", andTooltip.Triggerpoints to it witharia-describedby. The tooltip is a description: an icon-only Trigger still needs its ownaria-label.- The tooltip opens at once on focus, and after
openDelay(700 ms) when the pointer rests on the Trigger. It does not open on touch. - It closes when focus leaves, when the Trigger is pressed, on Escape, and after
closeDelay(300 ms) when the pointer leaves. - Moving the pointer from the Trigger onto the tooltip keeps it open, so that it can be read (WCAG 1.4.13 Content on Hover or Focus).
- Focus never moves into the tooltip.
Keyboard Interactions#
| Key | Description |
|---|---|
Tab | Focusing the Trigger shows the tooltip; leaving it hides the tooltip. |
Escape | Hides the tooltip. Focus stays on the Trigger. |