ez-tip

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

• Import and call render()

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

• Add data-ez-tip to any element

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

• 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):

Variable	Default	Description
--ez-tooltip-background-color	#FFFFFF	Tooltip background color
--ez-tooltip-color	#1A1A1A	Tooltip text color
--ez-tooltip-padding	0 0.5rem	Tooltip padding (CSS shorthand)
--ez-tooltip-border-radius	3px	Tooltip border radius

// 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

Attribute	Type	Default	Description
data-ez-tip	string	—	Required. HTML content or text for the tooltip.
data-ez-tip-hover	true or false	true	If false, tooltip is always visible; if true (or absent), shows on hover only.
data-ez-tip-delay	number (ms)	0	Milliseconds to wait after hover before showing the tooltip.
data-ez-tip-position	top,bottom,left,right		Preferred placement; library will auto-fallback to best-fit if it doesn’t fit.
data-ez-tip-background	string		Force background color for a single tooltip
data-ez-tip-color	string		Force text color for a single tooltip
data-ez-tip-padding	string		Force padding for a single tooltip
data-ez-tip-border-radius	string		Force border-radius for a single tooltip

<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