or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-tooltip.mdevent-delegation.mdglobal-utilities.mdindex.mdplugins.mdsingleton-tooltips.md
tile.json

tessl/npm-tippy-js

The complete tooltip, popover, dropdown, and menu solution for the web

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tippy.js@6.3.x

To install, run

npx @tessl/cli install tessl/npm-tippy-js@6.3.0

index.mddocs/

Tippy.js

Tippy.js is the complete tooltip, popover, dropdown, and menu solution for the web. It provides a powerful, feature-rich system for creating highly customizable interactive elements with automatic positioning, animations, and accessibility features built on top of Popper.js.

Package Information

  • Package Name: tippy.js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install tippy.js

Core Imports

import tippy from "tippy.js";
import "tippy.js/dist/tippy.css"; // Required CSS

For named exports:

import tippy, { hideAll, delegate, createSingleton, roundArrow } from "tippy.js";
// Plugins
import { animateFill, followCursor, inlinePositioning, sticky } from "tippy.js";
// CSS
import "tippy.js/dist/tippy.css";

Headless (without default animations):

import tippy from "tippy.js/headless";
// All other exports available too
import { hideAll, delegate, createSingleton } from "tippy.js/headless";

CommonJS:

const tippy = require("tippy.js").default;
// CSS (using a bundler that supports CSS imports)
require("tippy.js/dist/tippy.css");
// or
const { default: tippy, hideAll } = require("tippy.js");

Basic Usage

import tippy from "tippy.js";

// Create a tooltip for a single element
const instance = tippy('#myButton', {
  content: 'My tooltip content',
  placement: 'top',
  animation: 'fade',
});

// Create tooltips for multiple elements
const instances = tippy('.tooltip', {
  content(reference) {
    return reference.getAttribute('data-tooltip');
  },
  placement: 'bottom',
});

// Show and hide programmatically
instance.show();
instance.hide();

// Update content dynamically
instance.setContent('New content');

Architecture

Tippy.js is built around several key components:

  • Core Factory Function: The main tippy() function creates and manages tooltip instances
  • Instance Management: Each tooltip is represented by an Instance object with lifecycle methods
  • Plugin System: Extensible plugin architecture for custom behaviors and animations
  • Popper.js Integration: Advanced positioning engine with collision detection and boundary awareness
  • Lifecycle Hooks: Comprehensive event system for customizing tooltip behavior
  • Theme System: CSS-based theming with built-in themes and custom theme support

Capabilities

Core Tooltip Creation

Primary factory function for creating tooltip instances with comprehensive configuration options and lifecycle management.

function tippy(
  targets: Element | Element[] | NodeList | string,
  optionalProps?: Partial<Props>
): Instance | Instance[];

interface Instance {
  clearDelayTimeouts(): void;
  destroy(): void;
  disable(): void;
  enable(): void;
  hide(): void;
  hideWithInteractivity(event: MouseEvent): void;
  id: number;
  plugins: Plugin[];
  popper: PopperElement;
  popperInstance: Popper.Instance | null;
  props: Props;
  reference: ReferenceElement;
  setContent(content: Content): void;
  setProps(partialProps: Partial<Props>): void;
  show(): void;
  state: {
    isEnabled: boolean;
    isVisible: boolean;
    isDestroyed: boolean;
    isMounted: boolean;
    isShown: boolean;
  };
  unmount(): void;
}

Core Tooltip API

Global Utilities

Global utility functions for managing multiple tooltips and accessing framework-level functionality.

function hideAll(options?: HideAllOptions): void;

interface HideAllOptions {
  duration?: number;
  exclude?: Instance | ReferenceElement;
}

// Static properties on tippy function
const tippy: {
  defaultProps: DefaultProps;
  setDefaultProps(partialProps: Partial<DefaultProps>): void;
  currentInput: { isTouch: boolean };
};

Global Utilities

Constants

Pre-defined constants for common tooltip styling and configuration.

/** SVG markup for rounded arrow shape */
const roundArrow: '<svg width="16" height="6" xmlns="http://www.w3.org/2000/svg"><path d="M0 6s1.796-.013 4.67-3.615C5.851.9 6.93.006 8 0c1.07-.006 2.148.887 3.343 2.385C14.233 6.005 16 6 16 6H0z"></path></svg>';

Event Delegation

Advanced event delegation system for handling tooltips on dynamically created elements and managing large sets of tooltip triggers.

function delegate(
  targets: Element | Element[] | NodeList | string,
  props: Partial<Props> & { target: string }
): Instance | Instance[];

Event Delegation

Singleton Tooltips

Singleton system for creating shared tooltips that can be displayed across multiple reference elements with smooth transitions.

function createSingleton(
  tippyInstances: Instance[],
  optionalProps?: Partial<CreateSingletonProps>
): CreateSingletonInstance;

interface CreateSingletonInstance extends Instance {
  setInstances(instances: Instance[]): void;
  show(target?: ReferenceElement | Instance | number): void;
  showNext(): void;
  showPrevious(): void;
}

Singleton Tooltips

Plugins

Built-in plugin system with four official plugins for advanced behaviors and effects.

// Official plugins
const animateFill: AnimateFill;
const followCursor: FollowCursor;
const inlinePositioning: InlinePositioning;
const sticky: Sticky;

interface Plugin {
  name?: string;
  defaultValue?: any;
  fn(instance: Instance): Partial<LifecycleHooks>;
}

Plugins

Core Types

type Content = 
  | string 
  | Element 
  | DocumentFragment 
  | ((ref: Element) => string | Element | DocumentFragment);

type Placement = 
  | 'auto' | 'auto-start' | 'auto-end'
  | 'top' | 'top-start' | 'top-end'
  | 'bottom' | 'bottom-start' | 'bottom-end'
  | 'right' | 'right-start' | 'right-end'
  | 'left' | 'left-start' | 'left-end';

interface GetReferenceClientRect {
  (): ClientRect | DOMRect;
  contextElement?: Element;
}

interface ReferenceElement<TProps = Props> extends Element {
  _tippy?: Instance<TProps>;
}

interface PopperElement<TProps = Props> extends HTMLDivElement {
  _tippy?: Instance<TProps>;
}

interface Props extends LifecycleHooks, RenderProps {
  animateFill: boolean;
  appendTo: 'parent' | Element | ((ref: Element) => Element);
  aria: {
    content?: 'auto' | 'describedby' | 'labelledby' | null;
    expanded?: 'auto' | boolean;
  };
  delay: number | [number | null, number | null];
  duration: number | [number | null, number | null];
  followCursor: boolean | 'horizontal' | 'vertical' | 'initial';
  getReferenceClientRect: null | GetReferenceClientRect;
  hideOnClick: boolean | 'toggle';
  ignoreAttributes: boolean;
  inlinePositioning: boolean;
  interactive: boolean;
  interactiveBorder: number;
  interactiveDebounce: number;
  moveTransition: string;
  offset: [number, number] | ((args: {
    placement: Placement;
    popper: Popper.Rect;
    reference: Popper.Rect;
  }) => [number, number]);
  placement: Placement;
  plugins: Plugin[];
  popperOptions: Partial<Popper.Options>;
  render: ((instance: Instance) => {
    popper: PopperElement;
    onUpdate?: (prevProps: Props, nextProps: Props) => void;
  }) | null;
  showOnCreate: boolean;
  sticky: boolean | 'reference' | 'popper';
  touch: boolean | 'hold' | ['hold', number];
  trigger: string;
  triggerTarget: Element | Element[] | null;
}

interface LifecycleHooks {
  onAfterUpdate(instance: Instance, partialProps: Partial<Props>): void;
  onBeforeUpdate(instance: Instance, partialProps: Partial<Props>): void;
  onCreate(instance: Instance): void;
  onDestroy(instance: Instance): void;
  onHidden(instance: Instance): void;
  onHide(instance: Instance): void | false;
  onMount(instance: Instance): void;
  onShow(instance: Instance): void | false;
  onShown(instance: Instance): void;
  onTrigger(instance: Instance, event: Event): void;
  onUntrigger(instance: Instance, event: Event): void;
  onClickOutside(instance: Instance, event: Event): void;
}

interface RenderProps {
  allowHTML: boolean;
  animation: string | boolean;
  arrow: boolean | string | SVGElement | DocumentFragment;
  content: Content;
  inertia: boolean;
  maxWidth: number | string;
  role: string;
  theme: string;
  zIndex: number;
}