1. Docs
  2. Tooltip

Tooltip Component

A customizable tooltip component that provides contextual information when users hover or focus on an element.

PopoverUnoCSS PresetTailwind Plugin
The Tooltip component is a lightweight, accessible UI element used to display additional information when users hover over or focus on an element. It leverages the Popover component from Flexilla for its core functionality and positioning, using flexipop under the hood.

Installation

To start, install the @flexilla/tooltip package, or skip this step if you’ve already installed @flexilla/flexilla.

Structure

Similar to Popover and Dropdown, the Tooltip require a trigger and a tooltip element:
  • data-tooltip-trigger: The element that triggers the tooltip.
  • data-tooltip-id: The unique identifier that links the trigger to the tooltip element.
  • Tooltip Element: The element that displays the tooltip content, linked via the data-tooltip-id provided by the trigger.
Here’s the markup 
<button data-tooltip-trigger data-tooltip-id="tooltip1">
  Hover over Me
</button>
<div id="tooltip1" role="tooltip">
  This is the tooltip content.
</div>

Example

Core Styling Requirements

The content element (e.g., the div with id="tooltip1") requires specific CSS properties for correct positioning if you are not using the Flexilla UnoCSS preset or the Flexilla Tailwind CSS plugin (which provide a ui-popper utility class).
If you are styling manually, ensure the following CSS is applied to your tooltip content element: 
.your-tooltip-content-class { /* Or apply directly to the ID #tooltip1 */
  position: fixed;
  top: var(--fx-popper-placement-y);
  left: var(--fx-popper-placement-x);
  /* Other styles like width, background, z-index, etc., as needed */
}
Explanation:
  • position: fixed;: This is essential for positioning the element relative to the viewport.
  • top: var(--fx-popper-placement-y);: Flexilla calculates the vertical position and exposes it via this CSS custom property.
  • left: var(--fx-popper-placement-x);: Flexilla calculates the horizontal position and exposes it via this CSS custom property.
If you are using the Flexilla UnoCSS preset or Tailwind plugin, adding the ui-popper class to your content element handles these requirements automatically. For example: <div id="tooltip1" class="ui-popper ...other-styles">...</div>

Initializing the Component

Once installed, import the Tooltip component and initialize it in your project. Since the Tooltip uses the same Popover functionality, the configuration is very similar to the Popover component. 
import { Tooltip } from '@flexilla/tooltip';

const myTooltip = new Tooltip('#tooltip1', {
  /* options here */
});

Options

The Tooltip component inherits its core options from the Popover, with default behavior disabling repositioning on scroll and window resize. You can still customize various aspects of the Tooltip behavior as follows: 
import type { Placement } from "flexipop";

export type TooltipOptions = {
  defaultState?: "open" | "close",
  preventFromCloseOutside?: boolean,
  preventCloseFromInside?: boolean,
  placement?: Placement,
  offsetDistance?: number,
  triggerStrategy?: "hover" | "click",
  popper?: {
    eventEffect: {
      disableOnScroll?: boolean,  // Default: true
      disableOnResize?: boolean   // Default: true
    }
  },
  beforeShow?: () => void,
  beforeHide?: () => void,
  onShow?: () => void,
  onHide?: () => void,
  onToggle?: ({ isHidden }: { isHidden?: boolean }) => void
};

Customizing the Tooltip

You can customize the tooltip’s placement, appearance, and behavior using the options object. Here’s an example with a custom fade-in animation when the tooltip appears: 
new Tooltip('#tooltip1', {
  placement: 'top',
  onShow: () => {
    console.log('Tooltip is shown');
  },
  popper: {
    eventEffect: {
      disableOnScroll: true,
      disableOnResize: true
    }
  }
});

Attributes

Attributes options

  • data-placement : define the placement of the tooltip
  • data-offset-distance : the equivalent of setting offsetDistance in options
  • data-default-state : define a default state of the tooltip (open|close), the equivalent of options.defaultState, must be (open|close)
  • data-prevent-close-outside : adding this attribute is similar to setting the option preventFromCloseOutside, no value required
  • data-prevent-close-inside : adding this attribute is similar to setting the option preventCloseFromInside, no value required

data-state Attribute

The data-state attribute is used to indicate the state of the tooltip element:
  • open: Indicates the tooltip is currently visible.
  • close: Indicates the tooltip is hidden. You can use this to change the tooltip Element behavior with CSS (hide, show) 
.myTooltip{
  display : none;
}
.myTooltip[data-state=open]{
  display : block;
}

aria-expanded Attribute

The aria-expanded attribute indicates if the trigger is expanded. If aria-expanded is true, then typically the data-state will also be open.
You can use it in CSS, for example, to animate an indicator within the trigger. 
.myTooltip-trigger[aria-expanded=true] .icon-indicator{
  /* style here  */
}

Methods

The Tooltip component also exposes methods for programmatic control:

show()

Manually show the tooltip. 
myTooltip.show();

hide()

Manually hide the tooltip. 
myTooltip.hide();

setShowOptions(/* options */)

Like show() method but here you can set the placement and offsetDistance if needed. 
myTooltip.setShowOptions({ placement: Placement, offsetDistance: number })