Tooltip

Introduction

The Tooltip component provides contextual information when users interact with an element. It supports multiple positioning options, themes, and can be triggered by hover, focus, or touch.

When to Use

  • To provide additional context or explanation for interface elements
  • To show full text when content is truncated
  • To display keyboard shortcuts or hints
  • To explain icon-only buttons or controls

Key Features

  • Flexible Positioning: Four positions available - top (default), bottom, left, or right
  • Customizable Delays: Configure open and close delays independently
  • Multiple Themes: Dark and light themes available
  • Accessible: Full keyboard navigation and screen reader support
  • Touch Support: Works on mobile devices with tap interactions
  • Auto-positioning: Automatically adjusts position to stay within viewport

Anatomy

<div class="pm7-tooltip">
  <div class="pm7-tooltip-trigger">
    <!-- Trigger element -->
  </div>
  <div class="pm7-tooltip-content" data-side="top">
    <!-- Tooltip content -->
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Basic Tooltip

This is a helpful tooltip

Positioning

Top tooltip
Right tooltip
Bottom tooltip
Left tooltip

Sizes

Small tooltip
Default size tooltip
Large tooltip with more content

Themes

Dark tooltip (default)
Light themed tooltip

Multiline Content

This is a multiline tooltip that contains
multiple lines of text to demonstrate
how text wrapping works in tooltips.
Usage:
class="pm7-tooltip-content
       pm7-tooltip-content--multiline"

Wide Tooltips

This is a large tooltip with extended width (400px max) that can contain more detailed information, code examples, or longer explanations without becoming too cramped.
Custom Width Example

This tooltip demonstrates a custom max-width of 600px for cases where you need to display even more content, such as detailed API documentation or complex code examples:

// Example: Button with all modifiers
<button class="pm7-button pm7-button--primary
               pm7-button--lg pm7-button--full">
  Click Me
</button>

With Delay

Opens after 200ms
Opens after 600ms

Multiline Content

This tooltip contains multiple lines of text to explain complex functionality.

It can include formatted content and maintains readability.

Icon Tooltips

Help
Click here to learn more

Installation

npm install @pm7/core

CSS Classes

Class Description
.pm7-tooltip Base tooltip container
.pm7-tooltip-trigger Element that triggers the tooltip
.pm7-tooltip-content Tooltip content container
.pm7-tooltip-arrow Arrow pointing to trigger
Size Modifiers
.pm7-tooltip-content--sm Small tooltip size (max-width: 200px)
.pm7-tooltip-content--lg Large tooltip size (max-width: 400px)
Theme Variants
.pm7-tooltip-content--light Light theme variant
Content Modifiers
.pm7-tooltip-content--multiline Multiline content support

Data Attributes

Attribute Type Default Description
data-side string top Position of tooltip: top (default), bottom, left, right
data-align string center Alignment: start, center, end (only works for top/bottom positions)
data-delay number 0 Delay before showing/hiding (ms)
data-open-delay number 0 Specific open delay (ms)
data-close-delay number 0 Delay before hiding (ms)

Basic Usage

<div class="pm7-tooltip">
  <button class="pm7-button pm7-tooltip-trigger">
    Hover for tooltip
  </button>
  <div class="pm7-tooltip-content" data-side="top">
    Tooltip content
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Positioning

Note: PM7 Tooltip supports 4 positions: top (default), bottom, left, and right. The data-align attribute only works for top and bottom positions.

<!-- Top position (default) -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Top</button>
  <div class="pm7-tooltip-content" data-side="top">
    Tooltip appears above
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Right position -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Right</button>
  <div class="pm7-tooltip-content" data-side="right">
    Tooltip appears to the right
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Bottom position -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Bottom</button>
  <div class="pm7-tooltip-content" data-side="bottom">
    Tooltip appears below
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Left position -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Left</button>
  <div class="pm7-tooltip-content" data-side="left">
    Tooltip appears to the left
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Top with alignment (only works for top/bottom) -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Top Start</button>
  <div class="pm7-tooltip-content" data-side="top" data-align="start">
    Aligned to start
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Sizes

<!-- Small size -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Small</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--sm" data-side="top">
    Compact tooltip
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Default size -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Default</button>
  <div class="pm7-tooltip-content" data-side="top">
    Regular tooltip content
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Large size -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Large</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--lg" data-side="top">
    Larger tooltip with more content space
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Themes

<!-- Dark theme (default) -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Dark</button>
  <div class="pm7-tooltip-content" data-side="top">
    Dark tooltip
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Light theme -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Light</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--light" data-side="top">
    Light themed tooltip
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

With Delays

Use delays to prevent tooltips from appearing during casual mouse movements. Recommended values depend on the use case.

<!-- Short delay (200ms) - Good for navigation -->
<div class="pm7-tooltip" data-open-delay="200">
  <button class="pm7-tooltip-trigger">Quick Info</button>
  <div class="pm7-tooltip-content" data-side="top">
    Opens after 200ms
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Medium delay (600ms) - Good for form fields -->
<div class="pm7-tooltip" data-open-delay="600">
  <button class="pm7-tooltip-trigger">Detailed Help</button>
  <div class="pm7-tooltip-content" data-side="top">
    Opens after 600ms
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Custom open and close delays -->
<div class="pm7-tooltip" data-open-delay="300" data-close-delay="150">
  <button class="pm7-tooltip-trigger">Custom Timing</button>
  <div class="pm7-tooltip-content" data-side="top">
    Opens after 300ms, closes after 150ms
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Multiline Content

<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Info</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--multiline" data-side="top" style="max-width: 250px;">
    This tooltip contains multiple lines of text.<br><br>
    It can include formatted content and maintains readability.
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Wide Tooltips

For cases where you need more space for detailed content, use the large size modifier or custom max-width.

<!-- Large tooltip with extended width (400px) -->
<div class="pm7-tooltip">
  <button class="pm7-tooltip-trigger">Wide Content</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--lg pm7-tooltip-content--multiline" data-side="top">
    This large tooltip can contain detailed information, 
    code examples, or longer explanations without becoming too cramped.
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

<!-- Custom width tooltip (600px) -->
<div class="pm7-tooltip" data-open-delay="300">
  <button class="pm7-tooltip-trigger">Extra Wide</button>
  <div class="pm7-tooltip-content pm7-tooltip-content--lg pm7-tooltip-content--light pm7-tooltip-content--multiline" 
       data-side="bottom" style="max-width: 600px;">
    <strong>Custom Width Example</strong><br><br>
    This tooltip has a custom max-width of 600px for displaying 
    extensive content like API documentation or complex code examples:<br><br>
    <code style="display: block; padding: 12px; background: var(--pm7-muted); border-radius: 4px; font-size: 12px;">
      // Example: Button with all modifiers<br>
      &lt;button class="pm7-button pm7-button--primary<br>
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pm7-button--lg pm7-button--full"&gt;<br>
      &nbsp;&nbsp;Click Me<br>
      &lt;/button&gt;
    </code>
    <div class="pm7-tooltip-arrow"></div>
  </div>
</div>

Recommended Delay Values

Use Case Open Delay Close Delay Rationale
Navigation items 200ms 0ms Quick response for menus
Form field help 600ms 100ms Avoid accidental triggers
Icon buttons 300ms 0ms Balance between speed and prevention
Detailed info 800ms 200ms Only show when user really hovers

JavaScript API

import { PM7Tooltip } from '@pm7/core';

    import '/packages/core/src/scripts/index.js';
// Initialize a tooltip
const element = document.querySelector('.pm7-tooltip');
const tooltip = new PM7Tooltip(element);

// Show tooltip programmatically
tooltip.show();

// Hide tooltip
tooltip.hide();

// Update position
tooltip.updatePosition();

// Destroy tooltip instance
tooltip.destroy();

// Listen for tooltip events
element.addEventListener('pm7:tooltip:show', (event) => {
  console.log('Tooltip shown', event.detail.tooltip);
});

element.addEventListener('pm7:tooltip:hide', (event) => {
  console.log('Tooltip hidden', event.detail.tooltip);
});

Advanced Examples

<!-- Tooltip with custom styling -->
<span class="pm7-tooltip" data-pm7-tooltip="Custom styled tooltip" data-pm7-tooltip-theme="dark">
  <button class="pm7-button pm7-button--primary">Dark Theme</button>
</span>

<!-- Tooltip with HTML content -->
<span class="pm7-tooltip" data-pm7-tooltip="<strong>Bold</strong> text in tooltip" data-pm7-tooltip-html="true">
  <button class="pm7-button pm7-button--outline">HTML Content</button>
</span>

<!-- Disabled button with tooltip -->
<span class="pm7-tooltip" data-pm7-tooltip="This button is currently disabled">
  <button class="pm7-button pm7-button--primary" disabled>Disabled</button>
</span>

Accessibility

  • Tooltips are announced to screen readers using ARIA live regions
  • Keyboard accessible - shows on focus, hides on blur
  • Escape key closes the tooltip
  • Uses aria-describedby to associate tooltip with trigger
  • Touch devices show tooltip on tap

Copy this link that can be used as documentation for working with this component:

https://raw.githubusercontent.com/patrickmast/pm7-ui/main/packages/core/src/components/tooltip/README.md

🤖 AI-Optimized Documentation

This link contains complete Markdown documentation that is perfectly readable by AI assistants, developers, and other automated systems. Directly accessible on GitHub - including all essential PM7 Tooltip implementation guidance.

Perfect for ChatGPT, Claude, and other AI code assistants