---
type: ai-agent-documentation
version: 2.0
component: Tooltip
status: stable
audience: ai-coding-agents-only
human-readable: false
category: feedback
framework-support:
- vanilla: true
- react: true
- vue: true
- angular: true
- svelte: true
---
# Component: Tooltip
DEFINITION: The Tooltip component provides a small, contextual popover that displays descriptive information when a user hovers over or focuses on an element. It is automatically positioned and managed.
## Installation
```bash
npm install @pm7/core
```
### CSS & JavaScript Import
REQUIRED: Import both the CSS and the main JavaScript file.
```javascript
// ES modules
import '@pm7/core/dist/pm7.css';
import '@pm7/core'; // Imports and initializes all components
// HTML
```
## Required Structure
The Tooltip component requires a main container with `data-pm7-tooltip`, a trigger element (`.pm7-tooltip-trigger`), a content element (`.pm7-tooltip-content`), and an arrow element (`.pm7-tooltip-arrow`) inside the content.
```html
Tooltip text here.
```
### Structural Rules
- **ALWAYS**: The main container MUST have `data-pm7-tooltip`.
- **ALWAYS**: The trigger element MUST have the class `.pm7-tooltip-trigger`.
- **ALWAYS**: The tooltip content MUST be wrapped in a `div` with the class `.pm7-tooltip-content`.
- **ALWAYS**: The `.pm7-tooltip-content` MUST contain a `div` with the class `.pm7-tooltip-arrow` as its last child.
- **NEVER**: Omit any of the required elements or classes.
## JavaScript API
### Initialization
Initialization is automatic when `@pm7/core` is imported. For dynamically added components, re-initialization is required.
```javascript
// For components added after initial page load
window.PM7.init();
```
### Instance Access
```javascript
const element = document.querySelector('[data-pm7-tooltip]');
const instance = element.PM7Tooltip;
```
### Methods
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| `show` | `(none)` | `void` | Displays the tooltip. |
| `hide` | `(none)` | `void` | Hides the tooltip. |
| `updatePosition` | `(none)` | `void` | Recalculates and adjusts the tooltip's position. |
| `destroy` | `(none)` | `void` | Removes all event listeners and cleans up the instance. |
### Events
| Event | When | Detail | Bubbles |
|---|---|---|---|---|
| `pm7:tooltip:show` | After the tooltip becomes visible | `{ tooltip: PM7TooltipInstance }` | YES |
| `pm7:tooltip:hide` | After the tooltip becomes hidden | `{ tooltip: PM7TooltipInstance }` | YES |
## Attributes
See /docs/ATTRIBUTES.md for cross-component attribute relationships.
| Attribute | Component(s) | Values | Required | Effect |
|---|---|---|---|---|
| `data-pm7-tooltip` | Tooltip | presence | YES | Initializes Tooltip component. |
| `data-side` | Tooltip | `top`, `bottom`, `left`, `right` | NO | Sets the primary placement side of the tooltip. |
| `data-align` | Tooltip | `start`, `center`, `end` | NO | Aligns the tooltip along its primary axis. |
| `data-open-delay` | Tooltip | number (ms) | NO | Delay before tooltip opens on hover. |
| `data-close-delay` | Tooltip | number (ms) | NO | Delay before tooltip closes on hover out. |
| `data-state` | Tooltip | `open`, `closed` | AUTO | Managed by JS to reflect component's open/closed state. |
| `aria-label` | Tooltip | string | YES (icon-only) | Provides an accessible name for an element when no visible text is available. |
| `aria-describedby` | Tooltip | ID of descriptive element | NO | Links an element to an element that describes it. |
| `role` | Tooltip | `tooltip` | AUTO | Defines the purpose or nature of an element. |
## CSS Classes
| Class | Required | When | Effect |
|---|---|---|---|
| `.pm7-tooltip` | AUTO | Applied by JS to the main container | Base styling for the tooltip container. |
| `.pm7-tooltip-trigger` | YES | On the element that triggers the tooltip | Styles the trigger element. |
| `.pm7-tooltip-content` | YES | On the element containing the tooltip text | Styles the tooltip popover content. |
| `.pm7-tooltip-arrow` | YES | Inside `.pm7-tooltip-content` | Creates the visual arrow pointing to the trigger. |
| `.pm7-tooltip-content--sm` | NO | For a smaller tooltip width | Sets max-width to 200px. |
| `.pm7-tooltip-content--lg` | NO | For a larger tooltip width | Sets max-width to 400px. |
| `.pm7-tooltip-content--light` | NO | For a light-themed tooltip | Applies a light background and dark text. |
| `.pm7-tooltip-content--multiline` | NO | For multiline text wrapping | Adjusts line-height and text alignment for multiline content. |
## Patterns
### Pattern: Basic Tooltip
```html
This is a basic tooltip.
```
### Pattern: Tooltip with Custom Placement
Use `data-side` for `top`, `bottom`, `left`, `right` and `data-align` for `start`, `center`, `end`.
```html
This tooltip appears at the top-end.
```
### Pattern: Tooltip with Custom Delays
Use `data-open-delay` and `data-close-delay` attributes on the `data-pm7-tooltip` container.
```html
Opens after 500ms, closes after 200ms.
```
## Anti-Patterns
### NEVER: Use simplified `data-pm7-tooltip="Tooltip text"` syntax
```html
This simplified syntax is not supported by the PM7 Tooltip component. It will not initialize or display correctly.
This is the correct structured tooltip.
```
### NEVER: Omit the `.pm7-tooltip-arrow` element
```html
No arrow here.
The arrow element is crucial for visual positioning and styling. Without it, the tooltip may look broken or misaligned.
Arrow is present.
```
### NEVER: Manually control tooltip visibility with CSS
```html
...
The Tooltip component manages its own visibility, positioning, and event listeners. Manual CSS control will interfere with its functionality and animations.
// Let the component handle visibility automatically on hover/focus, or use the JavaScript API methods `show()` and `hide()`.
```
## React Integration
> **📚 Framework Integration Guide**: For Vue, Angular, and other framework integrations, see the comprehensive [Framework Integration Guide](https://raw.githubusercontent.com/patrickmast/pm7-ui/main/README-Framework-Integration.md)
### Basic Tooltip Usage in React
PM7-UI Tooltips work seamlessly in React applications:
```jsx
function TooltipExample() {
useEffect(() => {
window.PM7?.initFramework();
}, []);
return (
This is helpful information about the button.
);
}
```
### Dynamic Tooltip Content
When tooltip content changes dynamically, ensure PM7 updates the positioning:
```jsx
function DynamicTooltip({ message, isLoading }) {
const tooltipRef = useRef(null);
useEffect(() => {
window.PM7?.initFramework();
}, []);
useEffect(() => {
// Update position when content changes
const tooltip = tooltipRef.current?.PM7Tooltip;
if (tooltip) {
tooltip.updatePosition();
}
}, [message]);
return (
{isLoading ? 'Loading...' : message}
);
}
```
### Icon Buttons with Tooltips
Common pattern for icon-only buttons that need text labels:
```jsx
function IconButton({ icon, label, onClick }) {
useEffect(() => {
window.PM7?.initFramework();
}, []);
return (
{label}
);
}
// Usage
}
label="Edit this item"
onClick={handleEdit}
/>
```
### Form Field Help Tooltips
Providing contextual help for form fields:
```jsx
function FormFieldWithHelp({ label, helpText, ...inputProps }) {
useEffect(() => {
window.PM7?.initFramework();
}, []);
return (
);
}
```
### Key Points for React:
- Tooltips are fully declarative - just provide the HTML structure
- Use `PM7.init()` when dynamically adding tooltips
- Update tooltip position when content changes with `updatePosition()`
- Tooltips handle their own event listeners and positioning
- Always include the arrow element for proper rendering
- Use `tabIndex={0}` on non-interactive triggers to ensure keyboard accessibility
## Rules
### ALWAYS
- **ALWAYS**: Use the full structured HTML pattern for the Tooltip component.
- **ALWAYS**: Ensure the trigger element is focusable (e.g., `