easy-tooltips

A lightweight, zero-dependency tooltip library using modern JavaScript and CSS.
Just add data-tooltip to any element! No setup or config required.

Live Demo

Features

• No dependencies
• Works with both mouse and touch
• Customizable via CSS variables
• Automatically repositions and shifts to fit the screen
• Smooth, non-interrupting animations (no flicker on rapid hover)
• Compatible with Vue, React, Svelte, and more

Quick Start

Install via npm

npm install easy-tooltips

import "easy-tooltips/styles.css"
import "easy-tooltips"

Or use via CDN

https://www.jsdelivr.com/package/npm/easy-tooltips

Add tooltips to your HTML

<button data-tooltip="Click to save your changes">Save</button>
<span data-tooltip="This field is required">Username *</span>
<div data-tooltip="Multi-line tooltips<br>are supported too">Info</div>

No additional setup is needed for Vue, React, Svelte, or other frameworks! Tooltips automatically update when the element updates!

Advanced Usage

Custom HTML

You can render custom HTML inside a tooltip using data-tooltip-src. The value can be either a CSS selector or the literal keyword next.

The matched element's content is copied into the tooltip.

Using a CSS selector Point to any element in the document.

<button data-tooltip-src="#tip-shipping">Shipping info</button>
<template id="tip-shipping">
  <strong>Free shipping</strong> on orders over £50<br>
  Delivered in 2 to 4 working days
</template>

Using next Use next to automatically pull content from the next DOM element. The source element is automatically hidden.

<button data-tooltip-src="next">Ingredients</button>
<div>
  <ul>
    <li>Oats</li>
    <li>Honey</li>
    <li>Sea salt</li>
  </ul>
</div>

Custom tooltip IDs

For styling specific tooltips:

<button data-tooltip="Special tooltip" data-tooltip-id="save-button">Save</button>

#save-button {
  --tooltip-background: #28a745;
  --tooltip-border-color: #1e7e34;
}

Customization

You can style tooltips using CSS variables (recommended) or by targeting the tooltip classes directly. Note that some CSS variables are required for proper positioning:

:root {
  /* Tooltip appearance */
  --tooltip-background: #fff;         /* Background color */
  --tooltip-border-color: #aaa;       /* Border color */
  --tooltip-border-size: 1px;         /* Border thickness */
  --tooltip-max-width: 100%;          /* Maximum tooltip width */
  
  /* Positioning (required for JS positioning) */
  --tooltip-vertical-distance: 16px;  /* Distance from trigger element */
  --tooltip-viewport-padding: 16px;   /* Minimum distance from screen edges */
  --tooltip-arrow-size: 12px;         /* Size of the arrow */
  --tooltip-arrow-edge-buffer: 12px;  /* How close the arrow can get to the edge of a tooltip */
  --tooltip-arrow-radius: 0;          /* Border radius of the arrow */
  
  /* Animation (required for JS timing) */
  --tooltip-animation-length: 0.15s;  /* Duration of fade animation */
  --tooltip-delay: 0.15s;             /* How long before the animation starts */
}

How it works

Easy-tooltips uses a smart positioning system that:

1. Detects viewport boundaries - Automatically positions tooltips above or below elements
2. Handles edge cases - Shifts tooltips horizontally when they would overflow the screen
3. Manages animations - Queues tooltip updates to prevent conflicts

License

MIT © Ewan Howell