Tailwind CSS Tooltip Plugin API

Headless, unstyled Tooltip plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

Installation

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

Terminal

                        
                          npm i @floating-ui/dom @preline/tooltip

Example

Hover over the buttons below to see the four tooltip directions: top, right, bottom, and left. Remove the [--placement:*] option to enable automatic positioning.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

                      
                        <div class="hs-tooltip 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>

JavaScript behavior

Class Options

Name	Description	Options	Default value
`[--trigger:*]`	Event to trigger a tooltip. Should be added to the container (.hs-tooltip).	"focus" \| "hover"	`hover`
`[--placement:*]`	Tooltip placement. If "auto", the tooltip will be positioned based on the available space. Should be added to the container (.hs-tooltip).	"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]`
`[--strategy:*]`	Sets the position to `absolute` instead of `fixed`, and removes the `transform` styles to position the menu `relative` to the relative parent block. Should be added to the container (.hs-tooltip).	"fixed" \| "absolute"	`absolute`
`[—-prevent-popper:*]`	Prevents Floating UI positioning calculation issue. Should be added to the container (.hs-tooltip).	"true" \| "false"	`false`

Selectors

Name	Description
`hs-tooltip`	Tooltip container.
`hs-tooltip-toggle`	Tooltip toggle.

Methods

The HSTooltip object is contained within the global window object

Method	Description
Public methods
`show()`	Force show tooltip.
`hide()`	Force hide tooltip.
`destroy()`	Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
`HSTooltip.getInstance(target, isInstance)`	Returns the element associated to the `target`. `target` should be a Node or string (valid selector) `isInstance` boolean. Returns the instance instead of Node if `true`
`HSTooltip.show(target)`	Shows the element associated to the `target`. `target` should be a Node or string (valid selector)
`HSTooltip.hide(target)`	Hides the element associated to the `target`. `target` should be a Node or string (valid selector)

Force show tooltip (public method).

                      
                        const tooltip = new HSTooltip(document.querySelector('#tooltip'));
                        const showBtn = document.querySelector('#show-btn');

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

Force show tooltip (static method).

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

                        showBtn.addEventListener('click', () => {
                          HSTooltip.show(document.querySelector('#tooltip'));
                        });

Open item (mixed).

                      
                        const { element } = HSTooltip.getInstance('#tooltip', true);
                        const showBtn = document.querySelector('#show-btn');

                        showBtn.addEventListener('click', () => {
                          element.show();
                        });

Events

Method	Description
`on:show`	Called when tooltip is shown.
`on:hide`	Called when tooltip is hidden.

An example where a function is run every time a tooltip shows.

                      
                        const el = HSTooltip.getInstance('#tooltip');

                        el.on('show', (instance) => {...});

Demo examples

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

Check out Preline UI Components

Tailwind CSS Tooltip Plugin API

On this page