@m3e/tooltip

The m3e-tooltip component provides contextual information in response to user interaction, enhancing comprehension and reducing ambiguity. Tooltips are positioned relative to a target element and support configurable delays for show and hide behavior. Use the for attribute to designate the element for which to provide a tooltip.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/tooltip

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/tooltip, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/tooltip/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/tooltip/dist/css-custom-data.json"]
}

🚀 Native Module Support

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/toolbar/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/[email protected]/+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/bidi": "/node_modules/@m3e/core/dist/bidi.js",
      "@m3e/core/platform": "/node_modules/@m3e/core/dist/platform.js"
    }
  }
</script>

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

🗂️ Elements

• m3e-tooltip — Adds additional context to a button or other UI element.

🧪 Examples

The following example illustrates connecting a tooltip to a button using the for attribute.

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

📖 API Reference

This section details the attributes, slots and CSS custom properties available for the m3e-tooltip component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------ | --------- | ------- | ---------------------------------------------------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | for | string | | The identifier of the interactive control to which this element is attached. | | hide-delay | number | 200 | The amount of time, in milliseconds, before hiding the tooltip. | | position | string | "top" | The position of the tooltip. | | show-delay | number | 0 | The amount of time, in milliseconds, before showing the tooltip. |

🧩 Slots

| Slot | Description | | ----------- | ----------------------------------- | | (default) | Renders the content of the tooltip. |

🎛️ CSS Custom Properties

| Property | Description | | ------------------------------------------- | ------------------------------------------ | | --m3e-tooltip-padding | Internal spacing of the tooltip container. | | --m3e-tooltip-min-width | Minimum width of the tooltip. | | --m3e-tooltip-max-width | Maximum width of the tooltip. | | --m3e-tooltip-min-height | Minimum height of the tooltip container. | | --m3e-tooltip-max-height | Maximum height of the tooltip. | | --m3e-tooltip-shape | Border radius of the tooltip container. | | --m3e-tooltip-container-color | Background color of the tooltip. | | --m3e-tooltip-supporting-text-color | Text color of supporting text. | | --m3e-tooltip-supporting-text-font-size | Font size of supporting text. | | --m3e-tooltip-supporting-text-font-weight | Font weight of supporting text. | | --m3e-tooltip-supporting-text-line-height | Line height of supporting text. | | --m3e-tooltip-supporting-text-tracking | Letter spacing of supporting text. |

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.