Search docs

Tooltip

A short description that appears when a button is hovered or focused.

Tooltip follows the Tooltip WAI-ARIA design pattern.

Undo the last change (Ctrl+Z)
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>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/tooltip

Anatomy#

import { Tooltip } from '@leve-ui/tooltip'; // or '@leve-ui/core'

<Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Content>
    <Tooltip.Arrow />
  </Tooltip.Content>
</Tooltip.Root>
PartElementDescription
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.

Undo the last change (Ctrl+Z)

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; content?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

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.

openDelay700number

The delay in ms before the tooltip opens when the pointer rests on the Trigger. Focus opens it at once.

closeDelay300number

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 attributeValue
data-leve-tooltipAlways present
data-state"open" | "closed"

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-tooltip-triggerAlways present
data-state"open" | "closed"

Content#

PropDefaultType
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.

sideOffset0number

The distance from the Trigger in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the tooltip to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

arrowPadding0number

The padding between the arrow and the corners of the tooltip, in px.

Also accepts all <span> attributes.

Data attributeValue
data-leve-tooltip-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping: "top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS variableValue
--leve-tooltip-anchor-widthThe width of the Trigger
--leve-tooltip-anchor-heightThe height of the Trigger
--leve-tooltip-available-widthThe width available in the viewport
--leve-tooltip-available-heightThe 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 attributeValue
data-leve-tooltip-arrowAlways present
data-sideThe final side of the Content

Accessibility#

Complies with the Tooltip WAI-ARIA design pattern.

  • Tooltip.Content renders role="tooltip", and Tooltip.Trigger points to it with aria-describedby. The tooltip is a description: an icon-only Trigger still needs its own aria-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#

KeyDescription
TabFocusing the Trigger shows the tooltip; leaving it hides the tooltip.
EscapeHides the tooltip. Focus stays on the Trigger.