Skip to content
WebJs
Menu

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function TooltipDemo() {
  return html`
    <ui-tooltip>
      <ui-tooltip-trigger>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Hover</button>
      </ui-tooltip-trigger>
      <ui-tooltip-content>
        <p>Add to library</p>
      </ui-tooltip-content>
    </ui-tooltip>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add tooltip

Usage

Importing the module registers the tooltip elements. Each tooltip keeps its own delay, and the short skip window after one closes is shared across the page.

import '#components/ui/tooltip.ts';
<ui-tooltip>
  <ui-tooltip-trigger>
    <button>Hover</button>
  </ui-tooltip-trigger>
  <ui-tooltip-content>
    <p>Add to library</p>
  </ui-tooltip-content>
</ui-tooltip>

Composition

Use the following composition to build a <ui-tooltip>:

ui-tooltip
├── ui-tooltip-trigger
└── ui-tooltip-content

Side

Use the side attribute on <ui-tooltip-content> to change the position of the tooltip.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';

const sides = ['left', 'top', 'bottom', 'right'] as const;

export default function TooltipSides() {
  return html`
    <div class="flex flex-wrap gap-2">
      ${sides.map((side) => html`
        <ui-tooltip>
          <ui-tooltip-trigger>
            <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit capitalize')}>
              ${side}
            </button>
          </ui-tooltip-trigger>
          <ui-tooltip-content side=${side}>
            <p>Add to library</p>
          </ui-tooltip-content>
        </ui-tooltip>
      `)}
    </div>
  `;
}
View Code

With Keyboard Shortcut

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { kbdClass } from '#components/ui/kbd.ts';
import { SaveIcon } from '#lib/ui/lucide.ts';

export default function TooltipKeyboard() {
  return html`
    <ui-tooltip>
      <ui-tooltip-trigger>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon-sm" aria-label="Save Changes" class=${buttonClass({ variant: 'outline', size: 'icon-sm' })}>
          ${SaveIcon()}
        </button>
      </ui-tooltip-trigger>
      <ui-tooltip-content>
        Save Changes <kbd data-slot="kbd" class=${kbdClass()}>S</kbd>
      </ui-tooltip-content>
    </ui-tooltip>
  `;
}
View Code

Disabled Button

Show a tooltip on a disabled button by wrapping it with a span.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function TooltipDisabled() {
  return html`
    <ui-tooltip>
      <ui-tooltip-trigger>
        <span class="inline-block w-fit">
          <button type="button" data-slot="button" data-variant="outline" data-size="default" disabled class=${buttonClass({ variant: 'outline' })}>
            Disabled
          </button>
        </span>
      </ui-tooltip-trigger>
      <ui-tooltip-content>
        <p>This feature is currently unavailable</p>
      </ui-tooltip-content>
    </ui-tooltip>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      content: 'Add to library',
      left: 'Left',
      top: 'Top',
      bottom: 'Bottom',
      right: 'Right',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      content: 'إضافة إلى المكتبة',
      left: 'يسار',
      top: 'أعلى',
      bottom: 'أسفل',
      right: 'يمين',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      content: 'הוסף לספרייה',
      left: 'שמאל',
      top: 'למעלה',
      bottom: 'למטה',
      right: 'ימין',
    },
  },
};

const sides = ['left', 'top', 'bottom', 'right'] as const;

// The provider is the dir attribute on the wrapper, so the buttons and the
// tips inside it render right to left.
export default function TooltipRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div dir=${dir} lang=${lang} class="flex flex-wrap gap-2">
      ${sides.map((side) => html`
        <ui-tooltip>
          <ui-tooltip-trigger>
            <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit capitalize')}>
              ${t[side]}
            </button>
          </ui-tooltip-trigger>
          <ui-tooltip-content side=${side}>${t.content}</ui-tooltip-content>
        </ui-tooltip>
      `)}
    </div>
  `;
}
View Code

API Reference

ui-tooltip

The root. It opens on hover and on focus after a delay, and Escape dismisses an open tip without moving focus. It also has show() and hide() methods.

AttributeTypeDefault
openbooleanfalse
delay-durationnumber, in ms700
skip-delay-durationnumber, in ms300

ui-tooltip-trigger

Wraps the control that shows the tip. The control is described by the tip through aria-describedby, so an icon-only control still needs its own aria-label.

ui-tooltip-content

The tip, rendered in the top layer with the Popover API.

AttributeTypeDefault
side"top" | "right" | "bottom" | "left""top"
align"center" | "start" | "end""center"
side-offsetnumber, in px4
align-offsetnumber, in px0