Edit Profile

Dark Mode

Copy config

Copy and paste the following code into your global.css file to apply the styles.

DISCLAIMER: This component is in
Beta
status. That means that it is ready for production, but the API might change.

Tooltip

A text label that appears when a user hovers, focuses, or touches an element.

  • Opens on hover or focus
  • Closes on trigger activation or Escape key press
  • Customizable open/close delays
  • Optional arrow component
  • Always portaled content
  • Accessibility with ARIA roles and keyboard interactions
  • Flipping to avoid overflow
  • Automatic placement adjustment

The Qwik UI Tooltip component provides additional information or context on hover, focus, or touch. It ensures accessibility and positioning with built-in ARIA roles and automatic placement adjustments.

Building blocks

import { component$ } from '@builder.io/qwik';
import { Tooltip } from '@qwik-ui/headless';
 
export default component$(() => {
  return (
    <Tooltip.Root delayDuration={800} gutter={4} flip placement="top">
      <Tooltip.Trigger>
        <button>Hover or Focus me</button>
      </Tooltip.Trigger>
      <Tooltip.Panel aria-label="Tooltip content">
        <Tooltip.Arrow width={10} height={5} />
        Tooltip content here
      </Tooltip.Panel>
    </Tooltip.Root>
  );
});

Anatomy Table

ComponentDescription
Tooltip.Root

The parent container for the tooltip trigger and panel.

Tooltip.Trigger

An element that opens the tooltip when interacted with.

Tooltip.Panel

An HTML element that contains the tooltip content.

Tooltip.Arrow

An optional arrow component to point to the trigger element.

What is a Tooltip?

A tooltip is a small text label that appears when a user hovers over, focuses on, or touches an element. It provides additional information or context.

When would I use a tooltip?

Tooltips are useful for displaying contextual information or additional details about an element without cluttering the UI. They enhance user experience by providing necessary information only when needed.

Use case examples

ComponentDescription
Form Field

Provide additional information or guidance about a form field.

Button

Explain what an action button does.

Icon

Give more context or definition to an icon.

Caveats

Styling open tooltips

.tooltip-panel[data-open] {
  background: lightblue;
}

Use the data-open and data-closed attributes on the <Tooltip.Panel> component to specifically style the tooltip when it's open.

Cross-browser Animations

Tooltip Behavior

Tooltips show when hovering over or focusing on the trigger element and dismiss when moving the mouse away or losing focus.

Floating Behavior

By default, the Qwik UI Tooltip will float above the trigger component.

To make a tooltip float, we use JavaScript to choose where the tooltip should be positioned.

Custom Floating Position

By default, tooltips will float above the trigger component.

When setting placement on the root, you can customize the position of the tooltip.

Above we have set the placement prop to right, so the <Tooltip.Panel> will be positioned to the right of the trigger.

Flip

Enabled by default, we can use the flip prop to flip its position based on the available space in the viewport.

To disable flipping, set flip={false} on the <Tooltip.Root>.

Gutter

The gutter property defines the space between the anchor element and the floating element.

Styling

Styles can be added normally like any other component in Qwik UI, such as adding a class.

If Tailwind is the framework of choice, then styles can be added using the arbitrary variant syntax or @apply command.

Transition declarations

Transitions use the same classes for entry and exit animations. Those being data-open and data-closed. They are explained more in the Caveats section.

CSS from the example:

.tooltip-transition {
  opacity: 0;
  transition:
    opacity 0.5s,
    display 0.5s,
    overlay 0.5s;
  transition-behavior: allow-discrete;
}

.tooltip-transition[data-open] {
  opacity: 1;
}

.tooltip-transition[data-closed] {
  opacity: 0;
}

Events

The tooltip contains a onOpenChange$ event that runs when the tooltip opens or closes. This can be used to trigger additional actions when the tooltip is opened or closed.

The tooltip is closed

Additional References

Qwik UI aims to be in line with the standard whenever possible. Our goal is to empower Qwik developers to create amazing experiences for their users.

To read more about tooltips you can check it out on:

Tooltip Root

PropTypeDescription
id
string

Tooltip's id. Should match the tooltip target.

delayDuration
number

A value that determines how long before the tooltip will be opened once triggered in milliseconds.

flip
boolean

Flips the placement of the tooltip when it starts to collide with the boundaries.

gutter
number

The space between the trigger element and the tooltip.

data-closing"
selector

Style the element when the tooltip is closing. This occurs when the popover has a delay set.

data-closed
selector

Style the element when the tooltip is closed.

data-opening
selector

Style the element when the tooltip is in the process of opening. This occurs when the popover has a delay set.

data-open
selector

Style the element when the tooltip is open.

onOpenChange$
QRL

QRL handler that runs when the tooltip opens or closes.

Tooltip Components

PropTypeDescription
Tooltip.Trigger

The element that triggers the tooltip.

Tooltip.Panel

The container for the tooltip content.

Tooltip.Arrow

An optional arrow component for the tooltip.

Example Usages

Basic:

Complex HTML: