General

Tooltip

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

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

Usage#

app.component.ts

import { WdsTooltipComponent } from '@wds/angular/tooltip';

Put the element the tooltip describes in the trigger slot and the text in the default slot. The trigger must be focusable, so keyboard users can open the tooltip too.

Examples#

Default#

The tooltip opens when the pointer rests over the trigger (200 ms) or the trigger gets keyboard focus, and closes when they leave, on a click or on Escape. It stays open while the pointer is over the bubble.

Hover Add to library

Show code

tooltip-default.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-default-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent],
  template: `
    <wds-tooltip>
      <wds-button slot="trigger" variant="outline">Hover</wds-button>
      Add to library
    </wds-tooltip>
  `,
})
export class TooltipDefaultDemo {}

Side#

side places the tooltip top (default), right, bottom or left of the trigger, and align along it (start, center, end). Without enough space the tooltip flips to the other side.

Left Add to library

Top Add to library

Bottom Add to library

Right Add to library

Show code

tooltip-side.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-side-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent],
  template: `
    <div class="flex flex-wrap gap-2">
      <wds-tooltip side="left">
        <wds-button slot="trigger" variant="outline">Left</wds-button>
        Add to library
      </wds-tooltip>
      <wds-tooltip side="top">
        <wds-button slot="trigger" variant="outline">Top</wds-button>
        Add to library
      </wds-tooltip>
      <wds-tooltip side="bottom">
        <wds-button slot="trigger" variant="outline">Bottom</wds-button>
        Add to library
      </wds-tooltip>
      <wds-tooltip side="right">
        <wds-button slot="trigger" variant="outline">Right</wds-button>
        Add to library
      </wds-tooltip>
    </div>
  `,
})
export class TooltipSideDemo {}

Icon buttons name their action with label and show it in a tooltip. When the tooltip only repeats the name, it is not added as a description. Once one tooltip is open, moving to the next button opens its tooltip at once, without the delay.

Bold

Italic

Underline

Show code

tooltip-toolbar.ts

import { Component } from '@angular/core';
import { WdsButtonGroupComponent } from '@wds/angular/button-group';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-toolbar-demo',
  imports: [WdsButtonGroupComponent, WdsTooltipComponent, WdsButtonComponent],
  template: `
    <wds-button-group aria-label="Text formatting">
      <wds-tooltip>
        <wds-button slot="trigger" variant="outline" size="icon" label="Bold">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8" /></svg>
        </wds-button>
        Bold
      </wds-tooltip>
      <wds-tooltip>
        <wds-button slot="trigger" variant="outline" size="icon" label="Italic">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="19" x2="10" y1="4" y2="4" /><line x1="14" x2="5" y1="20" y2="20" /><line x1="15" x2="9" y1="4" y2="20" /></svg>
        </wds-button>
        Italic
      </wds-tooltip>
      <wds-tooltip>
        <wds-button slot="trigger" variant="outline" size="icon" label="Underline">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 4v6a6 6 0 0 0 12 0V4" /><line x1="4" x2="20" y1="20" y2="20" /></svg>
        </wds-button>
        Underline
      </wds-tooltip>
    </wds-button-group>
  `,
})
export class TooltipToolbarDemo {}

Keyboard shortcut#

A wds-kbd in a tooltip gets colors that fit the dark bubble. Give the button aria-keyshortcuts as well, so screen readers announce the shortcut.

Save

Ctrl

Show code

tooltip-keyboard-shortcut.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsKbdComponent, WdsKbdGroupComponent } from '@wds/angular/kbd';

@Component({
  selector: 'app-tooltip-keyboard-shortcut-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent, WdsKbdGroupComponent, WdsKbdComponent],
  template: `
    <wds-tooltip>
      <wds-button slot="trigger" variant="outline" size="icon" label="Save" aria-keyshortcuts="Control+S">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15.2 3a2 2 0 0 1 1.4.6l3.8 3.8a2 2 0 0 1 .6 1.4V19a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z" /><path d="M17 21v-7a1 1 0 0 0-1-1H8a1 1 0 0 0-1 1v7" /><path d="M7 3v4a1 1 0 0 0 1 1h7" /></svg>
      </wds-button>
      Save
      <wds-kbd-group><wds-kbd>Ctrl</wds-kbd><wds-kbd>S</wds-kbd></wds-kbd-group>
    </wds-tooltip>
  `,
})
export class TooltipKeyboardShortcutDemo {}

Description#

A tooltip that says more than the name becomes the description of the trigger (aria-description): screen readers read "Notifications, button, 3 unread notifications".

3 unread notifications

Show code

tooltip-description.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-description-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent],
  template: `
    <wds-tooltip side="bottom">
      <wds-button slot="trigger" variant="outline" size="icon" label="Notifications" class="relative">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.268 21a2 2 0 0 0 3.464 0" /><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326" /></svg>
      </wds-button>
      3 unread notifications
    </wds-tooltip>
  `,
})
export class TooltipDescriptionDemo {}

Rich content#

The bubble can hold a title and a few lines of text (up to --wds-tooltip-max-width, default 20rem). Keep it short and without links or buttons: the bubble cannot be focused. For interactive content use Popover.

Version history Pro

Pro feature Version history keeps every change for 90 days. It is part of the Pro plan.

Show code

tooltip-rich-content.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsBadgeComponent } from '@wds/angular/badge';

@Component({
  selector: 'app-tooltip-rich-content-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent, WdsBadgeComponent],
  template: `
    <wds-tooltip side="right">
      <wds-button slot="trigger" variant="outline">
        Version history
        <wds-badge variant="secondary">Pro</wds-badge>
      </wds-button>
      <div class="flex max-w-56 flex-col gap-1">
        <span class="font-medium">Pro feature</span>
        <span class="opacity-80">Version history keeps every change for 90 days. It is part of the Pro plan.</span>
      </div>
    </wds-tooltip>
  `,
})
export class TooltipRichContentDemo {}

Disabled button#

A disabled button cannot be focused and gets no pointer events, so wrap it in an element with tabindex="0" and make that the trigger. The tooltip can then explain why the action is not available.

Publish

Only editors can publish

Show code

tooltip-disabled.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-disabled-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent],
  template: `
    <wds-tooltip>
      <span slot="trigger" tabindex="0" class="inline-flex rounded-md">
        <wds-button disabled>Publish</wds-button>
      </span>
      Only editors can publish
    </wds-tooltip>
  `,
})
export class TooltipDisabledDemo {}

Delay and arrow#

On hover the tooltip opens after delay milliseconds (default 200), so tooltips do not flash while the pointer crosses the page. Keyboard focus opens it at once. delay="0" opens it on hover at once, hide-arrow removes the arrow.

Default Opens after 200 ms

No delay Opens at once

No arrow Without the arrow

Show code

tooltip-delay.ts

import { Component } from '@angular/core';
import { WdsTooltipComponent } from '@wds/angular/tooltip';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-tooltip-delay-demo',
  imports: [WdsTooltipComponent, WdsButtonComponent],
  template: `
    <div class="flex flex-wrap gap-2">
      <wds-tooltip>
        <wds-button slot="trigger" variant="outline">Default</wds-button>
        Opens after 200 ms
      </wds-tooltip>
      <wds-tooltip delay="0">
        <wds-button slot="trigger" variant="outline">No delay</wds-button>
        Opens at once
      </wds-tooltip>
      <wds-tooltip hide-arrow>
        <wds-button slot="trigger" variant="outline">No arrow</wds-button>
        Without the arrow
      </wds-tooltip>
    </div>
  `,
})
export class TooltipDelayDemo {}

API References#

A short text label that appears when the trigger is hovered or focused with the keyboard. The bubble opens in the top layer (Popover API) and stays open while the pointer is over it, so its text can be selected and zoomed in. The tooltip text becomes the trigger's description (aria-description). When it only repeats the trigger's name (e.g. an icon button with label="Bold" and the tooltip "Bold"), it is not added, so screen readers do not read the name twice. A tooltip holds plain text: no links or buttons, use wds-popover for those.

Attributes

Attribute	Type	Default	Description
open	boolean	false	Whether the tooltip is visible. Also set by `show()` and `hide()`.
side	WdsTooltipSide	'top'	Side of the trigger. Flips when there is not enough space.
align	WdsTooltipAlign	'center'	Alignment along the trigger.
offset	number	8	Distance from the trigger in px.
delay	number	200	Delay in ms between the pointer entering the trigger and the tooltip opening, so tooltips do not flash while the pointer passes over the page. Keyboard focus opens it at once, and so does moving to the next trigger while a tooltip is open or has just closed.
disabled	boolean	false	Turns the tooltip off (it does not open, and an open one closes).
hide-arrow.hideArrow	boolean	false	Hides the arrow.

Events

Event	Description
wds-open-changeCustomEvent<WdsTooltipOpenChangeDetail>	The tooltip opens or closes.

Methods

Method	Description
show()	Shows the tooltip.
hide()	Hides the tooltip.

Slots

Slot	Description
trigger	The element the tooltip describes (e.g. `wds-button`). It must be focusable: wrap a disabled button in an element with `tabindex="0"`.
(default)	Tooltip text. A `wds-kbd` gets colors that fit the dark bubble.

CSS parts (::part)

Part	Description
content	The bubble.
arrow	The arrow pointing at the trigger.

CSS custom properties

Property	Description
--wds-tooltip-bg	Background (default `--wds-foreground`).
--wds-tooltip-fg	Text color (default `--wds-background`).
--wds-tooltip-max-width	Maximum width of the bubble (default 20rem).

Accessibility#

The bubble has role="tooltip". Its text is set as aria-description on the trigger (wds-button forwards it to the native button), so screen readers read it after the name and the role.

When the text is the same as the name of the trigger (its label, aria-label or text), no description is added, so the name is not read twice. Name icon buttons with label: a tooltip is not a name.

Do not put interactive elements (links, buttons) in a tooltip: it closes when focus leaves the trigger. Use wds-popover for them.

The tooltip follows WCAG 1.4.13 "Content on hover or focus": it can be dismissed with Escape without moving focus, the pointer can move onto it without closing it, and it stays until the pointer or focus leaves.

Touch screens have no hover, so a tooltip does not open on touch. Do not hide information that is needed to use the page only in a tooltip.

Keyboard support#

Key	Function
Tab	Moves focus to the trigger and opens the tooltip. Moving focus away closes it.
Escape	Closes the tooltip; focus stays on the trigger.

Usage#

Examples#

Default#

Side#

Toolbar#

Keyboard shortcut#

Description#

Rich content#

Disabled button#

Delay and arrow#

API References#

wds-tooltip#

Attributes

Events

Methods

Slots

CSS parts (::part)

CSS custom properties

Accessibility#

Screen reader#

Keyboard support#