Tooltipster - Documentation

Getting Started

Installation

Tooltipster can be installed via npm or yarn. For npm, use the following command:

npm install tooltipster

For yarn, use:

yarn add tooltipster

Alternatively, you can include Tooltipster directly from a CDN. Include the CSS and JavaScript files in your HTML <head>:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tooltipster@latest/dist/css/tooltipster.bundle.min.css">
<script src="https://cdn.jsdelivr.net/npm/tooltipster@latest/dist/js/tooltipster.bundle.min.js"></script>

(Remember to replace "https://cdn.jsdelivr.net/npm/tooltipster@latest/..." with the actual CDN link if it changes). Ensure the paths are correct for your project setup.

Basic Usage

After installation, initiate Tooltipster on any element with a class or ID. The most basic usage involves selecting the target element and calling the tooltipster() method. This will create a tooltip with the element’s title attribute as content.

$(document).ready(function() {
  $('[data-tooltipster]').tooltipster();
});

This assumes your HTML includes elements like this:

<span data-tooltipster="Tooltip text here">Hover over me</span>

The data-tooltipster attribute is optional; if omitted, it will attempt to use the title attribute instead. If you use title then ensure it doesn’t display natively. Consider using CSS title { display: none; }

Quick Examples

Example 1: Basic Tooltip with Content from title attribute:

<p title="This is a tooltip">Hover over me</p>

<script>
  $(document).ready(function() {
    $('p').tooltipster();
  });
</script>

Remember to style title { display: none; } if needed.

Example 2: Custom Content:

<button id="myButton">Click Me</button>

<script>
  $(document).ready(function() {
    $('#myButton').tooltipster({
      content: $('<span>This is custom content!</span>')
    });
  });
</script>

Example 3: Changing the Tooltip’s Position:

<a id="myLink" href="#">Link</a>

<script>
  $(document).ready(function() {
    $('#myLink').tooltipster({
      position: 'bottom'
    });
  });
</script>

This will place the tooltip below the link. Other possible positions include top, left, right. Refer to the full documentation for a complete list of options and advanced configurations.

Configuration Options

Content

The content option specifies the text or HTML content displayed in the tooltip. It can be a string, a jQuery object, or a function.

Position

This option controls the tooltip’s position relative to the target element. Possible values include: 'top', 'top-left', 'top-right', 'bottom', 'bottom-left', 'bottom-right', 'left', 'left-top', 'left-bottom', 'right', 'right-top', 'right-bottom'. Defaults to 'top'.

Theme

The theme option allows you to customize the tooltip’s appearance using pre-defined themes or custom CSS. Tooltipster provides several built-in themes (e.g., 'tooltipster-default', 'tooltipster-shadow', etc.). You can also create your own custom theme by defining your own CSS classes.

Animations

Tooltipster supports various animations for showing and hiding tooltips. The animation option can be set to: 'fade', 'grow', 'swing', or 'none'. You can also provide custom animation functions.

Events

Tooltipster triggers various events throughout its lifecycle (e.g., 'show', 'shown', 'hide', 'hidden', 'update', 'creation'). These events can be used to perform custom actions in response to tooltip events.

Callbacks

Callbacks allow you to execute custom functions at specific points during the tooltip’s lifecycle. These include onShow, onShown, onHide, onHidden, onUpdate, onContentReady. Each callback receives the tooltip instance as an argument.

Distance

The distance option sets the spacing (in pixels) between the tooltip and the target element. Defaults to 0.

MaxWidth

The maxWidth option limits the tooltip’s width (in pixels or percentage). This helps prevent tooltips from overflowing their container.

Delay

The delay option controls the delay (in milliseconds) before the tooltip appears (or disappears). It can be a single number for both show and hide delays, or an object with separate show and hide properties.

Trigger

Specifies the event that triggers the tooltip’s appearance. Possible values: 'hover', 'click', 'custom' (requires defining custom events), ‘focus’. Defaults to ‘hover’.

AutoClose

The autoClose option controls whether the tooltip automatically closes when another tooltip is shown. Set to true to enable this behavior (default).

Multiple Tooltips

Tooltipster allows displaying multiple tooltips on a page simultaneously. The configuration options directly control the behavior of each tooltip instance.

Content Update

The content option can be updated dynamically after the tooltip is initialized, using the update() method. This allows for refreshing the tooltip’s content based on changes in the application state.

Accessibility

Tooltipster is designed with accessibility in mind. By default it uses ARIA attributes to ensure proper screen reader compatibility. You should ensure proper semantic HTML for your target elements to make sure screen readers work as expected. Custom themes should also maintain accessibility best practices.

Advanced Usage

Customizing Themes

To create a custom theme, you’ll need to define your own CSS classes. Start by inspecting the default Tooltipster CSS to understand the structure and classes used. Then, create a new CSS file and define your custom styles targeting the relevant classes (e.g., .tooltipster-base, .tooltipster-content, .tooltipster-arrow). Then, apply this custom theme using the theme option in your Tooltipster initialization:

$('.my-element').tooltipster({
  theme: 'my-custom-theme'
});

Using Templates

For more complex tooltip layouts, use templates. Create an HTML template element and set its ID. Then, reference this template ID in the Tooltipster configuration using the template option:

<template id="myTooltipTemplate">
  <div class="my-custom-tooltip">
    <span class="tooltip-title"></span>
    <div class="tooltip-content"></div>
  </div>
</template>

<script>
  $('.my-element').tooltipster({
    template: '#myTooltipTemplate'
  });
</script>

You can then style this template using CSS to achieve your desired look.

Handling Events

Tooltipster offers several events you can listen to and respond to using jQuery’s .on() method:

$('.my-element').on('tooltipster:show', function() {
  console.log('Tooltip is about to show!');
});

$('.my-element').on('tooltipster:shown', function(event, $tooltip) {
    // $tooltip is the tooltip's jQuery object
    console.log('Tooltip is shown:', $tooltip);
});

$('.my-element').on('tooltipster:hide', function() {
  console.log('Tooltip is about to hide!');
});

$('.my-element').on('tooltipster:hidden', function() {
  console.log('Tooltip is hidden!');
});

Consult the documentation for a full list of events.

Integration with Other Libraries

Tooltipster should integrate well with most JavaScript libraries. If conflicts arise, ensure proper initialization order, potentially wrapping Tooltipster initialization within a callback of the other library.

Troubleshooting

If tooltips are not appearing, check the following: * Correct Initialization: Ensure Tooltipster is properly included and initialized on the target element(s). * CSS Conflicts: Check for any CSS conflicts that might be hiding the tooltip. Use your browser’s developer tools to inspect the tooltip’s styles. * jQuery Dependency: Make sure jQuery is included before Tooltipster. * Conflicting JavaScript: Other scripts may interfere; test by temporarily disabling other plugins. * Incorrect Options: Review the Tooltipster configuration options for any errors or misconfigurations. Consult the console for any JavaScript errors.

Performance Optimization

For a large number of tooltips, consider these optimizations: * Lazy Initialization: Initialize tooltips only when they are needed (e.g., when the user interacts with an element). Use the trigger option to only show tooltips on hover or click rather than on page load. * Content Caching: If the content is not dynamic, pre-compute it and store it for later use to avoid redundant calculations. * Reduce DOM Manipulation: Avoid unnecessary DOM manipulations during tooltip creation and updates.

Working with Frameworks (React, Vue, Angular)

React: Use Tooltipster within a React component’s useEffect hook to initialize after the component renders. Wrap the Tooltipster call to avoid conflicts with React’s virtual DOM.

Vue: Use Tooltipster within a Vue component’s mounted lifecycle hook. Consider using a custom directive to simplify the process.

Angular: Use Tooltipster within an Angular component’s AfterViewInit lifecycle hook. You may need to use a custom directive or a service to manage Tooltipster initialization and cleanup.

Remember to handle the cleanup in the respective component’s componentWillUnmount (React), beforeDestroy (Vue), or ngOnDestroy (Angular) lifecycle hooks to prevent memory leaks. For more complex integrations, consult the specific framework’s documentation for best practices on using third-party libraries.

API Reference

Tooltipster Instance Methods

Instance methods are called on a specific Tooltipster instance. To get an instance, you can use the tooltipster('instance') method.

Tooltipster Static Methods

Static methods are called directly on the Tooltipster object itself.

Event Handling

Tooltipster provides several custom events that you can listen for using jQuery’s .on() method (or equivalent in other frameworks). These events are triggered at various points in the tooltip’s lifecycle. Some key events include:

The event handler receives the event object as the first argument and, in some cases, additional arguments (e.g. the tooltip instance, the tooltip content).

Data Attributes

Tooltipster supports several data attributes to configure tooltips directly in HTML. These can be used as an alternative to configuring tooltips via JavaScript. Some important data attributes include:

These data attributes provide a convenient way to configure simple tooltips directly in your HTML, while leaving more complex configurations to JavaScript. Remember that JavaScript configuration will override any conflicting data attributes.

Migration Guide

From Older Versions

Migrating from older versions of Tooltipster to the latest version might require some adjustments depending on the version you’re upgrading from. Check the release notes for your specific version range to identify breaking changes. Generally, the most significant changes between major versions are documented there.

However, here are some common areas to review when migrating:

It’s recommended to start by updating to the nearest minor version (e.g., from v4.2 to v4.3, then v4.3 to v4.4, and so on) before finally upgrading to the latest major version. This incremental approach will make it easier to identify and resolve any migration issues. Each release usually contains detailed information on breaking changes. If you encounter any problems, consult the latest documentation and release notes, or seek support from the Tooltipster community.