ez-tip

A lightweight, zero-dependency JavaScript tooltip library that uses CSS custom properties for full styling flexibility. Tooltips can be triggered on hover or displayed permanently, with configurable delay, offset, and positioning.

DEMO

Features

• Easy to integrate: Just import the JS and call render()
• CSS variables for styling: Customize colors, padding, radii, and offsets without touching the JS
• Configurable delay: Set a show delay per-instance or globally
• Smart positioning: Automatically chooses the best placement (top, bottom, left, right) or honors your preference
• Auto-update: Repositions on scroll/resize/element resize
• Auto-cleanup: Removes tooltips when their target elements are removed from the DOM

Installation

Install via npm/yarn:

npm install ez-tip
# or
yarn add ez-tip

Note: This library ships only JS. You must provide minimal CSS in your project to style the tooltip using the CSS variables defined below.

Quick Start

1. Import and call render()

   import { render } from "ez-tip";
   
   // Optional: pass a global debounce delay (ms) for repositioning
   render({ delay: 100 });

2. Add data-ez-tip to any element

   <button data-ez-tip="Hello, world!">Hover me</button>

3. Provide CSS to style the tooltip

   /* e.g. in your global stylesheet */
   :root {
     --tooltip-arrow-size: 6px;
   }
   
   .ez-tip {
     background-color: var(--ez-tooltip-background-color);
     color: var(--ez-tooltip-color);
     padding: var(--ez-tooltip-padding);
     border-radius: var(--ez-tooltip-border-radius);
     opacity: 0;
     transition: opacity 0.2s ease-in-out, transform 0.2s ease-in-out;
   }
   
   .ez-tip.ez-tip-visible {
     opacity: 1;
   }
   
   .ez-tip::after {
     content: "";
     position: absolute;
     width: 0;
     height: 0;
     border-style: solid;
   }
   
   /* ─── TOP placement ───
    Tooltip sits above the element,
    arrow on the bottom edge pointing DOWN toward the element */
   .ez-tip[data-position="top"]::after {
     bottom: calc(-1 * var(--tooltip-arrow-size));
     left: 50%;
     transform: translateX(-50%);
     border-width: var(--tooltip-arrow-size) var(--tooltip-arrow-size) 0 var(--tooltip-arrow-size);
     border-color: var(--ez-tooltip-background-color) transparent transparent transparent;
   }
   
   /* ─── BOTTOM placement ───
    Tooltip sits below the element,
    arrow on the top edge pointing UP toward the element */
   .ez-tip[data-position="bottom"]::after {
     top: calc(-1 * var(--tooltip-arrow-size));
     left: 50%;
     transform: translateX(-50%);
     border-width: 0 var(--tooltip-arrow-size) var(--tooltip-arrow-size) var(--tooltip-arrow-size);
     border-color: transparent transparent var(--ez-tooltip-background-color) transparent;
   }
   
   /* ─── LEFT placement ───
    Tooltip sits to the left of the element,
    arrow on the right edge pointing RIGHT toward the element */
   .ez-tip[data-position="left"]::after {
     right: calc(-1 * var(--tooltip-arrow-size));
     top: 50%;
     transform: translateY(-50%);
     border-width: var(--tooltip-arrow-size) 0 var(--tooltip-arrow-size) var(--tooltip-arrow-size);
     border-color: transparent transparent transparent var(--ez-tooltip-background-color);
   }
   
   /* ─── RIGHT placement ───
    Tooltip sits to the right of the element,
    arrow on the left edge pointing LEFT toward the element */
   .ez-tip[data-position="right"]::after {
     left: calc(-1 * var(--tooltip-arrow-size));
     top: 50%;
     transform: translateY(-50%);
     border-width: var(--tooltip-arrow-size) var(--tooltip-arrow-size) var(
         --tooltip-arrow-size
       ) 0;
     border-color: transparent var(--ez-tooltip-background-color) transparent transparent;
   }

API

render(options?: EzTipOptions)

Initializes tooltips for all elements with data-ez-tip. The library listens to the ready state of the dom.

• options.delay? — number
  • Global debounce delay (in ms) for repositioning on scroll/resize.
  • Default: 0

interface EzTipOptions {
  delay?: number;
}

Configuration

Before or after calling render(), you can override default styles globally by setting CSS variables on the <body> (or any ancestor):

// in JS before `render()` or anytime later
document.body.style.setProperty("--ez-tooltip-background-color", "#222");
document.body.style.setProperty("--ez-tooltip-offset", "12px");

// or import the config object and change the values directly:

import { render, config } from "ez-tip";

config.backgroundColor = "#E1E5E8";
config.color = "#4A4A4A";
config.padding = "0 0.5rem";
config.borderRadius = "5px";

Data Attributes

<button
  data-ez-tip="Detailed info"
  data-ez-tip-hover="true"
  data-ez-tip-delay="300"
  data-ez-tip-offset="10"
  data-ez-tip-position="bottom"
>
  Show at bottom on hover with a 300ms delay
</button>

Examples

Basic tooltip

<button data-ez-tip="Simple tooltip">Hover me</button>

Tooltip with delay and custom offset

<button data-ez-tip="Delayed" data-ez-tip-delay="500" data-ez-tip-offset="16">
  Delayed tooltip
</button>

Always-visible tooltip

<p data-ez-tip="Persistent" data-ez-tip-hover="false">Persistent tooltip</p>

Cleanup

Tooltips auto-remove themselves if their target element is removed from the DOM—no memory leaks or orphan nodes.

License

MIT © Alec Lloyd Probert