CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tippy-js

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

Pending
Overview
Eval results
Files

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;
}

Install with Tessl CLI

npx tessl i tessl/npm-tippy-js
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tippy.js@6.3.x
Badge
tessl/npm-tippy-js badge