5.0.0 • Published yesterday

@preline/tooltip

Licence

Licensed under MIT and Preline UI Fair Use License

Version

5.0.0

Deps

Size

166 kB

Vulns

Weekly

Stars

6.4K

Summary Dependency Versions

A tooltip is a floating, non-actionable label used to explain a user interface element or feature.

Overview
Installation
Basic usage
Configuration Options
JavaScript API
Events
Common Patterns
License

Overview

The Tooltip component provides contextual information when users hover over or focus on an element. It supports multiple placement options, customizable triggers, and integrates with Floating UI for advanced positioning.

Key Features:

Multiple placement options (top, bottom, left, right, auto)
Customizable trigger events (hover, focus)
Floating UI integration for smart positioning
Programmatic control via JavaScript API
Event system for lifecycle hooks
Accessibility support (ARIA attributes)

Installation

To get started, install Tooltip & Popover plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i @preline/tooltip

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/tooltip */
@source "../node_modules/@preline/tooltip/*.js";
@import "./node_modules/@preline/tooltip/variants.css";
@import "./node_modules/@preline/tooltip/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/@preline/tooltip/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script type="module">
  import HSTooltip from "@preline/tooltip/non-auto.mjs";

  new HSTooltip(document.querySelector("#tooltip"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

@preline/tooltip is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import "@preline/tooltip";

@preline/tooltip/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import HSTooltip from "@preline/tooltip/non-auto";

HSTooltip.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#tooltip");
if (el) new HSTooltip(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a tooltip component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The tooltip appears when hovering over the button.

<div class="hs-tooltip [--placement:auto] inline-block">
  <button type="button" class="hs-tooltip-toggle">
    Hover me
    <span class="hs-tooltip-content hs-tooltip-shown:opacity-100 hs-tooltip-shown:visible opacity-0 transition-opacity inline-block absolute invisible z-10 py-1 px-2 bg-gray-900 text-white" role="tooltip">
      Tooltip on top
    </span>
  </button>
</div>

Structure Requirements:

hs-tooltip: Required container wrapper
hs-tooltip-toggle: Required element that triggers the tooltip (button, link, etc.)
hs-tooltip-content: Required element containing the tooltip content
Proper ARIA attributes (role="tooltip")

Configuration Options

CSS Classes (Modifiers)

CSS class modifiers use Tailwind-style syntax with -- prefix to control tooltip behavior.

Class Modifier	Target Element	Values	Default	Description
`[--trigger:*]`	`hs-tooltip` (container)	`"focus"` \| `"hover"`	`"hover"`	Event to trigger a tooltip. `hover` shows on mouse enter, `focus` shows on focus.
`[--placement:*]`	`hs-tooltip` (container)	`"auto"` \| `"top"` \| `"top-left"` \| `"top-right"` \| `"bottom"` \| `"bottom-left"` \| `"bottom-right"` \| `"right"` \| `"right-top"` \| `"right-bottom"` \| `"left"` \| `"left-top"` \| `"left-bottom"`	`"auto"` (top → bottom, left → right)	Tooltip placement relative to the trigger element. If `"auto"`, the tooltip will be positioned based on available space.
`[--strategy:*]`	`hs-tooltip` (container)	`"fixed"` \| `"absolute"`	`"absolute"`	Sets the position strategy. `fixed` positions relative to viewport, `absolute` positions relative to the nearest positioned ancestor.
`[--prevent-popper:*]`	`hs-tooltip` (container)	`"true"` \| `"false"`	`"false"`	Prevents Floating UI positioning calculation issues. Set to `"true"` if experiencing positioning problems.

Example:

<div class="hs-tooltip --trigger:focus --placement:bottom">
  <button class="hs-tooltip-toggle">Focus me</button>
  <span class="hs-tooltip-content">Tooltip content</span>
</div>

Required CSS Classes

These classes define the structure and must be present for the tooltip to function.

Class	Required On	Purpose
`hs-tooltip`	Container wrapper	Groups the toggle and content elements together
`hs-tooltip-toggle`	Trigger element	The element that activates the tooltip (button, link, etc.)
`hs-tooltip-content`	Content element	The tooltip content that appears on trigger

JavaScript API

The HSTooltip object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a tooltip instance.

Method	Parameters	Return Type	Description
`show()`	None	`void`	Forces the tooltip to show programmatically.
`hide()`	None	`void`	Forces the tooltip to hide programmatically.
`destroy()`	None	`void`	Destroys the tooltip instance, removes all generated markup, classes, and event listeners. Use when removing tooltip from DOM.

Static Methods

These methods are called directly on the HSTooltip class.

Method	Parameters	Return Type	Description
`HSTooltip.getInstance(target, isInstance)`	`target`: `HTMLElement \| string` (CSS selector) `isInstance`: `boolean` (optional)	`{ id: string \| number, element: HSTooltip } \| HTMLElement \| null`	Returns the tooltip instance or element associated with the target. If `isInstance` is `true`, returns collection item object `{ id, element }` where `element` is the `HSTooltip` instance. If `isInstance` is `false` or omitted, returns the DOM element (`HTMLElement`). Returns `null` if tooltip instance is not found.
`HSTooltip.show(target)`	`target`: `HSTooltip \| HTMLElement \| string` (CSS selector)	`void`	Shows the tooltip identified by target. Accepts a tooltip instance, DOM element, or CSS selector string. Static alternative to instance `show()` method.
`HSTooltip.hide(target)`	`target`: `HSTooltip \| HTMLElement \| string` (CSS selector)	`void`	Hides the tooltip identified by target. Accepts a tooltip instance, DOM element, or CSS selector string. Static alternative to instance `hide()` method.

Usage Examples

Example 1: Using instance methods (public API)

// Create a new tooltip instance
const tooltip = new HSTooltip(document.querySelector('#hs-tooltip'));
const showBtn = document.querySelector('#hs-show-btn');

// Show tooltip programmatically
showBtn.addEventListener('click', () => {
  tooltip.show();
});

Example 2: Using static methods

const showBtn = document.querySelector('#hs-show-btn');

// Show tooltip using static method (no instance needed)
showBtn.addEventListener('click', () => {
  HSTooltip.show(document.querySelector('#hs-tooltip'));
});

Example 3: Getting instance and using methods (recommended pattern)

// Get the tooltip instance
const instance = HSTooltip.getInstance('#hs-tooltip', true);

if (instance) {
  const { element } = instance; // element is the HSTooltip instance
  const showBtn = document.querySelector('#hs-show-btn');

  // Use instance methods
  showBtn.addEventListener('click', () => {
    element.show();
  });

  // Clean up when removing from DOM
  function removeTooltip() {
    element.destroy();
  }
}

Example 4: Destroying tooltip instance

const instance = HSTooltip.getInstance('#hs-tooltip', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-tooltip').remove();
  });
}

Events

Tooltip instances emit events that can be listened to for lifecycle hooks and custom behavior.

Event Name	When Fired	Callback Parameter	Description
`on:show`	After tooltip is shown	`HSTooltip` (tooltip instance)	Fires after the tooltip has been displayed. Use for post-show actions like tracking analytics.
`on:hide`	After tooltip is hidden	`HSTooltip` (tooltip instance)	Fires after the tooltip has been hidden. Use for cleanup or state updates.

Event Usage Example

// Get tooltip instance
const instance = HSTooltip.getInstance('#hs-tooltip', true);

if (instance) {
  const { element } = instance;

  // Listen to show event
  element.on('show', (tooltipInstance) => {
    console.log('Tooltip shown:', tooltipInstance);
    // Perform actions after tooltip shows
    // e.g., track analytics, update UI
  });

  // Listen to hide event
  element.on('hide', (tooltipInstance) => {
    console.log('Tooltip hidden:', tooltipInstance);
    // Perform cleanup or state updates
  });
}

Common Patterns

Show tooltip on focus for keyboard accessibility.

<div class="hs-tooltip --trigger:focus --placement:bottom">
  <button class="hs-tooltip-toggle">Focus me</button>
  <span class="hs-tooltip-content">Helpful information</span>
</div>

Pattern 2: Programmatic Control

Control tooltip from external buttons.

<div class="hs-tooltip" id="hs-tooltip-first">
  <button class="hs-tooltip-toggle">Hover me</button>
  <span class="hs-tooltip-content">Tooltip content</span>
</div>

<button id="hs-show-tooltip">Show Tooltip</button>
<button id="hs-hide-tooltip">Hide Tooltip</button>

<script>
  const instance = HSTooltip.getInstance('#hs-tooltip-first', true);
  
  if (instance) {
    const { element } = instance;

    document.querySelector('#hs-show-tooltip').addEventListener('click', () => {
      element.show();
    });

    document.querySelector('#hs-hide-tooltip').addEventListener('click', () => {
      element.hide();
    });
  }
</script>

License

Licensed under the MIT License.