Tooltip

<wa-tooltip>

Stable

Tooltips display brief contextual information when the user hovers, focuses, or taps a target element.

This is a tooltip
Hover Me

<wa-tooltip for="my-button">This is a tooltip</wa-tooltip>
<wa-button appearance="filled" id="my-button">Hover Me</wa-button>

Point the for attribute at the id of the element the tooltip describes, and Web Awesome wires up positioning and accessibility for you.

Keep tooltips to text and presentational content.
Tooltips can't be reliably focused or operated with a keyboard, so avoid buttons, links, and form controls inside one. Reach for a popover or dropdown when you need interactive content.

Examples

Link to This Section

Placement

Link to This Section

Use the placement attribute to set the tooltip's preferred position. The actual placement may shift to keep the tooltip inside the viewport.

    
top-starttoptop-endleft-startright-startleftrightleft-endright-endbottom-startbottombottom-end

<div class="tooltip-placement-example">
  <div class="tooltip-placement-example-row">
    <wa-button appearance="filled" id="tooltip-top-start"></wa-button>
    <wa-button appearance="filled" id="tooltip-top"></wa-button>
    <wa-button appearance="filled" id="tooltip-top-end"></wa-button>
  </div>

  <div class="tooltip-placement-example-row">
    <wa-button appearance="filled" id="tooltip-left-start"></wa-button>
    <wa-button appearance="filled" id="tooltip-right-start"></wa-button>
  </div>

  <div class="tooltip-placement-example-row">
    <wa-button appearance="filled" id="tooltip-left"></wa-button>
    <wa-button appearance="filled" id="tooltip-right"></wa-button>
  </div>

  <div class="tooltip-placement-example-row">
    <wa-button appearance="filled" id="tooltip-left-end"></wa-button>
    <wa-button appearance="filled" id="tooltip-right-end"></wa-button>
  </div>

  <div class="tooltip-placement-example-row">
    <wa-button appearance="filled" id="tooltip-bottom-start"></wa-button>
    <wa-button appearance="filled" id="tooltip-bottom"></wa-button>
    <wa-button appearance="filled" id="tooltip-bottom-end"></wa-button>
  </div>
</div>

<wa-tooltip for="tooltip-top-start" placement="top-start">top-start</wa-tooltip>
<wa-tooltip for="tooltip-top" placement="top">top</wa-tooltip>
<wa-tooltip for="tooltip-top-end" placement="top-end">top-end</wa-tooltip>
<wa-tooltip for="tooltip-left-start" placement="left-start">left-start</wa-tooltip>
<wa-tooltip for="tooltip-right-start" placement="right-start">right-start</wa-tooltip>
<wa-tooltip for="tooltip-left" placement="left">left</wa-tooltip>
<wa-tooltip for="tooltip-right" placement="right">right</wa-tooltip>
<wa-tooltip for="tooltip-left-end" placement="left-end">left-end</wa-tooltip>
<wa-tooltip for="tooltip-right-end" placement="right-end">right-end</wa-tooltip>
<wa-tooltip for="tooltip-bottom-start" placement="bottom-start">bottom-start</wa-tooltip>
<wa-tooltip for="tooltip-bottom" placement="bottom">bottom</wa-tooltip>
<wa-tooltip for="tooltip-bottom-end" placement="bottom-end">bottom-end</wa-tooltip>

<style>
  .tooltip-placement-example {
    width: 250px;
    margin: 1rem;
  }

  .tooltip-placement-example wa-button {
    width: 2.5rem;
  }

  .tooltip-placement-example-row {
    display: flex;
    justify-content: space-between;
    gap: 0.5rem;
    margin-bottom: 0.5rem;
  }

  .tooltip-placement-example-row:nth-child(1),
  .tooltip-placement-example-row:nth-child(5) {
    justify-content: center;
  }
</style>

Triggers

Link to This Section

The trigger attribute controls how a tooltip is activated. Pass multiple values separated by a space to combine them — the default is hover focus, which shows the tooltip on pointer hover and keyboard focus.

Value	Shows the tooltip when
`hover`	The pointer moves over the target
`focus`	The target receives keyboard focus
`click`	The target is clicked; clicking again dismisses it
`manual`	Only when you set `open` yourself — no built-in activation

Click to Toggle
Click again to dismiss

<wa-button appearance="filled" id="toggle-button">Click to Toggle</wa-button>
<wa-tooltip for="toggle-button" trigger="click">Click again to dismiss</wa-tooltip>

HTML in Tooltips

Link to This Section

Use the default slot to add presentational HTML, such as emphasis or line breaks.

Hover me
This tooltip includes formatted content, such as emphasis and line breaks.

<wa-button appearance="filled" id="rich-tooltip">Hover me</wa-button>
<wa-tooltip for="rich-tooltip">
  <div>This tooltip includes <strong>formatted</strong> content, such as <em>emphasis</em> and line breaks.</div>
</wa-tooltip>

Customizing

Link to This Section

Use the --max-width custom property to set the width at which the tooltip's content wraps.

  This tooltip will wrap after only 80 pixels.

Hover me

<wa-tooltip for="wrapping-tooltip" style="--max-width: 80px;">
  This tooltip will wrap after only 80 pixels.
</wa-tooltip>
<wa-button appearance="filled" id="wrapping-tooltip">Hover me</wa-button>

Remove the arrow on a single tooltip with the without-arrow attribute.

No Arrow
This is a tooltip with no arrow

<wa-button appearance="filled" id="no-arrow">No Arrow</wa-button>
<wa-tooltip for="no-arrow" without-arrow>This is a tooltip with no arrow</wa-tooltip>

Resize the arrow on every tooltip with the --wa-tooltip-arrow-size design token. Set it in a :root block after the Web Awesome stylesheet loads — 0 removes arrows globally.

:root {
  --wa-tooltip-arrow-size: 0;
}

Showing & Hiding Manually

Link to This Section

Set trigger="manual" and toggle the open attribute to control the tooltip yourself — handy for onboarding hints or surfacing a tooltip in response to your own logic.

  This is an avatar!
  
  Toggle Manually

<div class="manual-trigger-example">
  <wa-tooltip for="manual-trigger-tooltip" trigger="manual" class="manual-tooltip">This is an avatar!</wa-tooltip>
  <wa-avatar id="manual-trigger-tooltip" label="User"></wa-avatar>

  <wa-divider></wa-divider>

  <wa-button appearance="filled" class="manual-toggle">Toggle Manually</wa-button>
</div>

<script>
  const tooltip = document.querySelector('.manual-tooltip');
  const toggle = document.querySelector('.manual-toggle');

  toggle.addEventListener('click', () => (tooltip.open = !tooltip.open));
</script>

API

Link to This Section

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN

npm

Self-Hosted

React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/[email protected]/components/tooltip/tooltip.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/webawesome/dist/components/tooltip/tooltip.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/tooltip/tooltip.js';

To import this component for React 18 or below, use the following code:

import WaTooltip from '@awesome.me/webawesome/dist/react/tooltip/index.js';

Slots

Link to This Section

Learn more about using slots.

Name	Description
(default)	The tooltip's default slot where any content should live. Interactive content should be avoided.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name	Description	Reflects
`disabled` `disabled`	Disables the tooltip so it won't show when triggered. Type `boolean` Default `false`
`distance` `distance`	The distance in pixels from which to offset the tooltip away from its target. Type `number` Default `8`
`hideDelay` `hide-delay`	The amount of time to wait before hiding the tooltip when the user mouses out. Type `number` Default `0`
`open` `open`	Indicates whether or not the tooltip is open. You can use this in lieu of the show/hide methods. Type `boolean` Default `false`
`placement` `placement`	The preferred placement of the tooltip. Note that the actual placement may vary as needed to keep the tooltip inside of the viewport. Type `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` Default `'top'`
`showDelay` `show-delay`	The amount of time to wait before showing the tooltip when the user mouses in. Type `number` Default `150`
`skidding` `skidding`	The distance in pixels from which to offset the tooltip along its target. Type `number` Default `0`
`trigger` `trigger`	Controls how the tooltip is activated. Possible options include `click`, `hover`, `focus`, and `manual`. Multiple options can be passed by separating them with a space. When manual is used, the tooltip must be activated programmatically. Type `string` Default `'hover focus'`
`withoutArrow` `without-arrow`	Removes the arrow from the tooltip. Type `boolean` Default `false`

Methods

Link to This Section

Learn more about methods.

Name	Description	Arguments
`hide()`	Hides the tooltip
`show()`	Shows the tooltip.

Events

Link to This Section

Learn more about events.

Name	Description
`wa-after-hide`	Emitted after the tooltip has hidden and all animations are complete.
`wa-after-show`	Emitted after the tooltip has shown and all animations are complete.
`wa-hide`	Emitted when the tooltip begins to hide.
`wa-show`	Emitted when the tooltip begins to show.

CSS Custom Properties

Link to This Section

Learn more about CSS custom properties.

Name	Description
`--max-width`	The maximum width of the tooltip before its content will wrap.

CSS Parts

Link to This Section

Learn more about CSS parts.

Name	Description	CSS selector
`base__arrow`	The popup's exported `arrow` part. Use this to target the tooltip's arrow.	`::part(base__arrow)`
`base__popup`	The popup's exported `popup` part. Use this to target the tooltip's popup container.	`::part(base__popup)`
`body`	The tooltip's body where its content is rendered.	`::part(body)`
`tooltip`	The component's outer wrapper.	`::part(tooltip)`
`base`	Deprecated. Use the `tooltip` part instead.	`::part(base)`

Dependencies

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

<wa-popup>

Need a hand?

Report a bug

Ask for help

Tooltip

Examples

Placement

Triggers

HTML in Tooltips

Customizing

Showing & Hiding Manually

API

Importing

Slots

Attributes & Properties

Methods

Events

CSS Custom Properties

CSS Parts

Dependencies

Quick Links

Recent Searches