The m3e-tooltip adds additional context displayed when the user hovers over or longpresses an element.

npm i @m3e/tooltip

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

Use the m3e-tooltip component to define a 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.

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.

This 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/tooltip/dist/index.js"></script>

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

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js",
      "@m3e/core/anchoring": "/node_modules/@m3e/core/dist/anchoring.js",
      "@m3e/core/platform": "/node_modules/@m3e/core/dist/platform.js"
    }
  }
</script>

For production, use index.min.js, a11y.min.js, anchoring.min.js, and platform.min.js for faster load times.

This 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.