Tooltip

Tooltip renders a small contextual popup near a target element to surface additional information without cluttering the layout. It automatically supports hover, touch, and focus interaction based on the target device, five placement options with automatic smart-positioning, and an optional directional arrow.

In React, Tooltip is initialized through the useTooltip hook without adding tooltip attributes to the element. In vanilla usage, FrontAlign can observe tooltip components automatically through the component engine.

Getting Started

Use the React hook for framework usage, or create an instance manually when working with plain JavaScript.

import { Tooltip } from 'frontalign';

const tooltip = new Tooltip('#save-btn', {
  message: 'Save your changes',
  placement: 'top',
  hasArrow: true
});

Automatic Discovery

For static markup, Tooltip can observe the DOM and initialize itself without a manual new Tooltip(...) call per element. Mark any element with fa-component="tooltip", then call new FrontAlign() once — it queries every match and creates an instance for each (or reuses the existing one if that element was already initialized).

<button fa-component="tooltip" data-tooltip="Save your changes" data-placement="top">
  Save
</button>

Only two attributes are read directly off the element — no JavaScript options object is required for basic usage:

hasArrow and autoClean have no data-attribute equivalent — they can only be set through the JavaScript options object. Elements that need those still work with Tooltip.init() for discovery, but require a manual instantiation instead if those options must differ from their defaults:

new Tooltip('#save-btn', { hasArrow: false, autoClean: true });

An already-initialized element's instance can be retrieved at any time with Tooltip.getInstance(element).

Tooltip supports five placement values. The default auto mode measures the free viewport space on all four sides of the target and picks whichever side has the most space relative to the tooltip's size — there is no fixed fallback order. If a specific placement is requested and there's enough room for it, that placement is honored as-is; otherwise the best-fitting side is chosen automatically, recalculating on every resize and scroll.

new Tooltip('#btn', { placement: 'auto'   }); // smart placement
new Tooltip('#btn', { placement: 'top'    });
new Tooltip('#btn', { placement: 'bottom' });
new Tooltip('#btn', { placement: 'left'   });
new Tooltip('#btn', { placement: 'right'  });

Arrow

Set hasArrow: true to render a directional arrow pointing toward the target. Enabled by default.

new Tooltip('#btn', { message: 'With arrow',    hasArrow: true  });
new Tooltip('#btn', { message: 'Without arrow', hasArrow: false });

Auto Clean

Set autoClean: true to have the instance call .dispose() automatically after the tooltip is removed. Useful for dynamic lists where manual cleanup is impractical.

new Tooltip('#btn', {
  message: 'This tooltip disposes after removal.',
  placement: 'top',
  autoClean: true
});

Configuration Reference

Class Reference