The @m3e/web/tooltip module provides plain and rich tooltip components for delivering contextual guidance, from simple hover descriptions to multi-line, expressive content anchored to a control.

import "@m3e/web/tooltip";

This section outlines usage examples and configuration guidance for the components in this package.

Use the m3e-tooltip component to define a plain tooltip, and apply the for attribute to associate it with a specific UI element.

<m3e-icon-button id="button">
  <m3e-icon name="arrow_back"></m3e-icon>
</m3e-icon-button>
<m3e-tooltip for="button">Go Back</m3e-tooltip>

By default, tooltips are positioned below the element. You can control a tooltip's position using the position attribute. Supported values include above, below (default), before, and after. The before and after positions are BIDI-aware, adapting to left-to-right and right-to-left text directions.

Use the show-delay and hide-delay attributes to control the amount of time, in milliseconds, to show or hide a tooltip. The following snippet illustrates the default delays.

<m3e-icon-button id="button">
  <m3e-icon name="arrow_back"></m3e-icon>
</m3e-icon-button>
<m3e-tooltip for="button" show-delay="0" hide-delay="200">Go Back</m3e-tooltip>

Use the disabled attribute to disable a tooltip from showing.

<m3e-icon-button id="button">
  <m3e-icon name="arrow_back"></m3e-icon>
</m3e-icon-button>
<m3e-tooltip for="button" disabled>Go Back</m3e-tooltip>

On touch devices, tooltips use a long-press gesture to show and hide. This can conflict with native browser gestures, such as text selection or drag interactions. To mitigate this, tooltips disables native gestures on the tooltip trigger by default. However, this behavior may not be desirable for certain elements like inputs or draggable components.

Use the touch-gestures attribute to specify how touch interactions are handled:

• auto — Enables touch gestures for all elements, while preserving native browser behaviors on inputs, textareas, and draggable elements.
• on — Enables touch gestures universally and disables all native browser gestures without exception.
• off — Disables touch gestures entirely, preventing tooltips from appearing on touch devices.

Use the m3e-rich-tooltip component to define a rich tooltip, and apply the for attribute to associate it with a specific UI element. The subhead slot specifies the subhead content and the default slot specifies supplementary text.

<m3e-icon-button id="button">
  <m3e-icon name="settings"></m3e-icon>
</m3e-icon-button>
<m3e-rich-tooltip for="button">
  <span slot="subhead">New settings available</span>
  Now you can adjust the uploaded image quality, and upgrade your available storage space.
</m3e-rich-tooltip>

Including interactive content in a rich tooltip promotes it to dialog-like behavior. The surface becomes dismissible and keyboard-navigable, and must be opened through an explicit user action on the trigger.

You can include actions in a rich tooltip using the actions slot. In addition, use the m3e-rich-tooltip-action component, nested in a clickable element, to dismiss the tooltip. By default, focus is returned to the trigger. Use the disable-restore-focus attribute of a m3e-rich-tooltip-action to disable this behavior.

<m3e-icon-button id="button">
  <m3e-icon name="settings"></m3e-icon>
</m3e-icon-button>
<m3e-rich-tooltip for="button">
  <span slot="subhead">New settings available</span>
  Now you can adjust the uploaded image quality, and upgrade your available storage space.
  <div slot="actions">
    <m3e-button>
      <m3e-rich-tooltip-action>Learn more</m3e-rich-tooltip-action>
    </m3e-button>
  </div>
</m3e-rich-tooltip>

By default, rich tooltips are positioned below and after the element. You can control a tooltip's position using the position attribute. Supported values include above-before, above-after,below-before, below-after (default), before, after, above and below. Positions are BIDI-aware, adapting to left-to-right and right-to-left text directions.

Plain and non-interactive tooltips add an aria-describedby description that provides a reference to a visually hidden element containing the tooltip's message. This allows screen readers to announce the tooltip's contents when the user focuses on the tooltip's trigger. The element referenced by aria-describedby is not the tooltip itself, but an invisible copy of its content that remains present in the DOM.

Interactive rich tooltips add aria-haspopup="dialog" to their trigger to correctly expose a dialog-like popup to assistive technologies. In addition, the tooltip's internal popover is given ARIA role="dialog" and is automatically labelled by tooltip's subhead.

The @m3e/web package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/web/dist/tooltip.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js",
      "@m3e/web/core/a11y": "/node_modules/@m3e/web/dist/core-a11y.js",
      "@m3e/web/core/anchoring": "/node_modules/@m3e/web/dist/core-anchoring.js",
      "@m3e/web/core/bidi": "/node_modules/@m3e/web/dist/core-bidi.js",
      "@m3e/web/core/platform": "/node_modules/@m3e/web/dist/core-platform.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.