### Start the development server Source: https://github.com/atomiks/tippyjs/blob/master/website/README.md Navigates to the project directory and launches the local development environment. ```sh cd my-default-starter/ gatsby develop ``` -------------------------------- ### Initialize basic tooltip Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/ajax.mdx Initial setup for the tooltip with a loading state. ```js tippy('#ajax-tippy', { content: 'Loading...', }); ``` -------------------------------- ### Initialize Tippy.js with CDN Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/getting-started.mdx Basic usage example showing how to call tippy() with a CSS selector and content prop. ```html Tippy ``` -------------------------------- ### Install Tippy.js via Package Managers Source: https://github.com/atomiks/tippyjs/blob/master/README.md Commands to install the library using npm or Yarn. ```bash # npm npm i tippy.js # Yarn yarn add tippy.js ``` -------------------------------- ### HTML Button Setup Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/ajax.mdx The target element for the tooltip. ```html ``` -------------------------------- ### Initialize Default Tippy Tooltip Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Basic setup for a tooltip triggered by mouseenter or focus events. ```html ``` ```js tippy('#myButton', { content: "I'm a Tippy tooltip!", }); ``` -------------------------------- ### Implementing a custom plugin Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/plugins.mdx Example of a plugin that hides the popper when elements within it lose focus. ```js const hideOnPopperBlur = { name: 'hideOnPopperBlur', defaultValue: true, fn(instance) { return { onCreate() { instance.popper.addEventListener('focusout', (event) => { if ( instance.props.hideOnPopperBlur && event.relatedTarget && !instance.popper.contains(event.relatedTarget) ) { instance.hide(); } }); }, }; }, }; // Our new prop is enabled by default (defaultValue: true) tippy(targets, { plugins: [hideOnPopperBlur], }); ``` -------------------------------- ### Announcing tooltip content with aria-describedby Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/accessibility.mdx Example of the DOM structure generated for non-interactive tooltips to ensure screen readers announce the content. ```html ``` -------------------------------- ### Navigate instances in order Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/addons.mdx Use showNext and showPrevious to cycle through child instances. ```js // if no child tippy is shown, show first one, otherwise show the next one singleton.showNext(); // if no child tippy is shown, show last one, otherwise show the previous one singleton.showPrevious(); ``` ```js singleton.show(0); // show first singleton.showPrevious(); // loops back and shows last item singleton.showNext(); // loops to the front and shows first item ``` -------------------------------- ### singleton.showNext() / singleton.showPrevious() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/addons.mdx Navigates through child tippy instances in order. ```APIDOC ## singleton.showNext() / singleton.showPrevious() ### Description Cycles through the child tippy instances in forward or reverse order. These methods loop back to the start or end respectively. ``` -------------------------------- ### Initial Tippy Configuration Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/ajax.mdx Basic initialization with flipOnUpdate enabled to handle size changes. ```js tippy('#ajax-tippy', { content: 'Loading...', // This prop is recommended if your tooltip changes size while showing flipOnUpdate: true, }); ``` -------------------------------- ### instance.show() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Programmatically show the tippy instance. ```APIDOC ### instance.show(duration?) #### Description Programmatically show the tippy at any time. #### Parameters - **duration** (number) - Optional - Transition duration in milliseconds. ``` -------------------------------- ### Create a new Gatsby site Source: https://github.com/atomiks/tippyjs/blob/master/website/README.md Initializes a new project using the Gatsby CLI and the default starter template. ```sh # create a new Gatsby site using the default starter npx gatsby new my-default-starter https://github.com/gatsbyjs/gatsby-starter-default ``` -------------------------------- ### Show on Create Configuration Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Determines if the tippy should show immediately upon creation. ```js tippy(targets, { // default showOnCreate: false, // enable it showOnCreate: true, }); ``` -------------------------------- ### Create a singleton instance Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Initialize a singleton using an array of existing tippy instances. ```javascript import tippy, {createSingleton} from 'tippy.js'; const tippyInstances = tippy('button'); const singleton = createSingleton(tippyInstances, {delay: 1000}); ``` -------------------------------- ### tippy() constructor Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx The main entry point for creating tooltips, accepting a target element and an optional configuration object containing props. ```APIDOC ## tippy(targets, options) ### Description Initializes a tippy instance on the specified target elements with the provided configuration options. ### Parameters - **targets** (String|Element|Array|NodeList) - Required - The element(s) to attach the tippy to. - **options** (Object) - Optional - An object containing configuration props such as `allowHTML`, `animation`, `appendTo`, etc. ``` -------------------------------- ### Show Instance Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Triggers the tooltip display, optionally specifying a transition duration in milliseconds. ```js instance.show(); // Default instance.show(0); // 0ms transition duration ``` -------------------------------- ### instance.enable() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Re-enable a tippy instance. ```APIDOC ### instance.enable() #### Description Re-enable a tippy instance. ``` -------------------------------- ### Create a globalStore plugin Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/plugins.mdx Manages a collection of all active tippy instances for bulk updates. ```js let tippyInstances = []; const globalStore = { fn(instance) { return { onCreate() { tippyInstances.push(instance); }, onDestroy() { tippyInstances = tippyInstances.filter((i) => i !== instance); }, }; }, }; // APIs to manipulate all tippy instances export function updateAll(props) { tippyInstances.forEach((instance) => { instance.setProps(props); }); } ``` -------------------------------- ### Using plugins in Node Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/plugins.mdx Importing and registering plugins in ESM or CJS environments. ```js import tippy, {followCursor} from 'tippy.js'; tippy(targets, { followCursor: true, plugins: [followCursor], }); ``` -------------------------------- ### Configure singleton transitions Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Use updateDuration to control the transition speed between singleton targets. ```javascript const singleton = createSingleton(tippyInstances, { delay: 1000, updateDuration: 500, }); ``` -------------------------------- ### Include Tippy.js via CDN Source: https://github.com/atomiks/tippyjs/blob/master/README.md Add the library to your HTML using unpkg script tags. ```html ``` -------------------------------- ### Importing Tippy.js Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/faq.mdx Standard import syntax for ESM or CJS environments. ```js import tippy from 'tippy.js'; // or const tippy = require('tippy.js').default; ``` -------------------------------- ### singleton.show(target) Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/addons.mdx Shows a specific child tippy instance within the singleton. ```APIDOC ## singleton.show(target) ### Description Displays the tooltip for a specific child instance. If no parameter is provided, it shows the first child. ### Parameters - **target** (TippyInstance | Element | Number) - Optional - The specific instance, reference element, or index to show. ``` -------------------------------- ### Create a singleton instance Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Groups multiple tippy instances to share a single tooltip element and timer. ```js tippy.createSingleton(tippy(buttons), { delay: 500, }); ``` -------------------------------- ### Import Tippy.js and Popper.js Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/motivation.mdx Standard import syntax for using Tippy.js alongside its underlying positioning engine, Popper.js. ```js import Popper from 'popper.js'; import tippy from 'tippy.js'; ``` -------------------------------- ### Applying a theme Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/themes.mdx Pass the theme name as a property to the tippy instance. ```js tippy('button', { theme: 'light', }); ``` -------------------------------- ### Enable follow cursor behavior Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Configures a tippy instance to follow the mouse cursor movement. ```js tippy(button, { followCursor: true, }); ``` -------------------------------- ### Combine global configuration and data attributes Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/customizing-tooltips.mdx Use the tippy() function for global defaults and data attributes for individual element overrides. ```html ``` ```js // Global config for all ``` -------------------------------- ### Create a context menu with Tippy.js Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/misc.mdx Uses a manual trigger and getReferenceClientRect to position the tooltip at the mouse cursor coordinates during a contextmenu event. ```js const rightClickableArea = document.querySelector('#container'); const instance = tippy(rightClickableArea, { content: 'Context menu', placement: 'right-start', trigger: 'manual', interactive: true, arrow: false, offset: [0, 0], }); rightClickableArea.addEventListener('contextmenu', (event) => { event.preventDefault(); instance.setProps({ getReferenceClientRect: () => ({ width: 0, height: 0, top: event.clientY, bottom: event.clientY, left: event.clientX, right: event.clientX, }), }); instance.show(); }); ``` -------------------------------- ### onCreate hook Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/lifecycle-hooks.mdx Executes once when the tippy instance is initially created. ```js tippy(reference, { onCreate(instance) { // ... }, }); ``` -------------------------------- ### Configure Browser Scripts for v5 Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Include the required Popper.js dependency and the Tippy.js bundle script in your HTML. ```html ``` -------------------------------- ### Configuration Props and Lifecycle Hooks Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/all-props.mdx A list of available configuration properties and lifecycle hooks for customizing Tippy.js behavior. ```APIDOC ## Configuration Props ### offset - **Type**: number | string - **Default**: 0 - **Description**: Determines the offset of the tippy element. Can work on both axes using a string in the form "x, y". ## Lifecycle Hooks ### onAfterUpdate - **Description**: Invoked after the tippy's props have been updated. ### onBeforeUpdate - **Description**: Invoked before the tippy's props have been updated. ### onCreate - **Description**: Invoked when the tippy has been created. ### onDestroy - **Description**: Invoked when the tippy has been destroyed. ### onHidden - **Description**: Invoked when the tippy has fully transitioned out and is unmounted from the DOM. ### onHide - **Description**: Invoked when the tippy begins to transition out. Returning `false` cancels the hide action. ### onMount - **Description**: Invoked when the tippy has been mounted to the DOM (called after onShow). ### onShow - **Description**: Invoked when the tippy begins to transition in. Returning `false` cancels the show action. ``` -------------------------------- ### Configure theme property Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Sets the theme for the tippy element. Defaults to a dark #333 theme. ```js tippy(targets, { // default theme: '', // custom theme theme: 'tomato', }); ``` -------------------------------- ### createSingleton(instances, options) Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Creates a single tippy element that manages an array of regular tippy instances. ```APIDOC ## createSingleton(instances, options) ### Description Groups multiple tippy instances into one, allowing for smooth transitions and shared delay behavior. ### Parameters - **instances** (Instance[]) - Required - An array of existing tippy instances. - **options** (object) - Optional - Configuration object. - **delay** (number) - Optional - Delay in milliseconds. - **updateDuration** (number) - Optional - Transition duration between position updates. - **boundary** (string) - Optional - Constraint boundary (e.g., 'viewport'). ``` -------------------------------- ### Import headless plugins Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/headless-tippy.mdx Ensure all plugins are imported from the headless package to avoid duplicate code. ```js import tippy, {followCursor} from 'tippy.js/headless'; ``` -------------------------------- ### Polyfill IE11 dependencies via polyfill.io Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/browser-support.mdx Include this script tag before Tippy's scripts to polyfill required APIs for IE11. ```html ``` -------------------------------- ### tippy() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/tippy-instance.mdx The tippy() function creates new instances and returns either a single instance or an array of instances depending on the input target. ```APIDOC ## tippy(target) ### Description Creates a new tippy instance for the provided target. Returns a single instance if the target is a single element, or an array of instances if the target is a string selector, NodeList, or array of elements. ### Parameters - **target** (Element | String | NodeList | Array) - Required - The target element(s) to attach the tooltip to. ### Returns - **Instance | Instance[]** - The created tippy instance or array of instances. ``` -------------------------------- ### Configure Animation Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Sets the transition animation for the tooltip. ```js tippy(button, { // default animation: 'fade', }); ``` -------------------------------- ### Import Optional CSS Animations Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/getting-started.mdx Demonstrates how to include extra CSS files for animations using module bundlers or CDN links. ```javascript import 'tippy.js/animations/scale.css'; ``` ```html ``` -------------------------------- ### Configuration Properties Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Various properties to configure the behavior, appearance, and positioning of the tippy instance. ```APIDOC ## Configuration Properties ### placement - **Type**: string - **Description**: The preferred placement of the tippy (e.g., 'top', 'bottom', 'right', 'left', 'auto'). ### plugins - **Type**: array - **Description**: Plugins to extend tippy functionality. ### popperOptions - **Type**: object - **Description**: Custom options passed directly to Popper.js for fine-grained positioning control. ### role - **Type**: string - **Description**: Specifies the `role` attribute on the tippy element (default: 'tooltip'). ### showOnCreate - **Type**: boolean - **Description**: Determines if the tippy is shown immediately upon creation. ### sticky - **Type**: boolean | string - **Description**: Determines if the tippy sticks to the reference element while mounted. Requires the sticky plugin. ``` -------------------------------- ### Include Development Version via CDN Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/getting-started.mdx Use the bundle file during development to receive helpful warnings and error messages. ```html ``` -------------------------------- ### Define a custom theme Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/themes.mdx Create a custom theme by targeting the .tippy-box element with the data-theme attribute. ```css .tippy-box[data-theme~='tomato'] { background-color: tomato; color: yellow; } ``` -------------------------------- ### delegate(targets, options) Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Creates a delegate instance that handles tippy creation for child elements matching a CSS selector. ```APIDOC ## delegate(targets, options) ### Description Allows a parent element to handle the creation of tippy instances for child elements, improving performance and handling dynamic content. ### Parameters - **targets** (string|Element|Element[]) - Required - The parent element(s) to act as a delegate. - **options** (object) - Required - Configuration object. - **target** (string) - Required - CSS selector matching the child elements. ### Return Value - **Instance|Instance[]** - Returns an opaque value representing the created instance(s). ### Cleanup - **destroy(shouldDestroyChildren: boolean)** - Destroys the delegate instance. If `shouldDestroyChildren` is true (default), it also destroys child instances. ``` -------------------------------- ### Initialize event delegation Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Use the delegate function to handle tippy creation for child elements via a parent. ```javascript import {delegate} from 'tippy.js'; delegate('#parent', { target: '.child', }); ``` -------------------------------- ### Enable followCursor plugin Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md The followCursor functionality now requires explicit plugin registration. ```js import tippy, {followCursor} from 'tippy.js'; tippy('button', { followCursor: true, plugins: [followCursor], }); ``` -------------------------------- ### onShow hook Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/lifecycle-hooks.mdx Executes when the tippy begins to show, before mounting to the DOM. Returning false cancels the show action. ```js tippy(reference, { onShow(instance) { // ... return false; // cancels it }, }); ``` -------------------------------- ### Applying a custom theme Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/themes.mdx Use the theme name without the -theme suffix in the configuration. ```js tippy('button', { theme: 'tomato', }); ``` -------------------------------- ### Initialize tooltips with data attributes Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/creating-tooltips.mdx Use the data-tippy-content attribute to define tooltip text on HTML elements. ```html ``` -------------------------------- ### instance.setContent(content) Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/methods.mdx Shortcut method to update the content prop. ```APIDOC ## instance.setContent(content) ### Description Updating the content prop has its own method as a shortcut. ``` -------------------------------- ### Update imports for Headless Tippy Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/headless-tippy.mdx Replace standard imports with the headless variants to enable the headless mode. ```diff - import tippy from 'tippy.js'; + import tippy from 'tippy.js/headless'; ``` ```diff - + ``` -------------------------------- ### Initialize tooltip with content prop Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/creating-tooltips.mdx Use the content property to define tooltip text for a single element. ```js tippy('#singleElement', { content: 'Tooltip', }); ``` -------------------------------- ### Implement custom rendering Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/headless-tippy.mdx Use the render prop to define the structure of the tippy element and handle updates. ```js import tippy from 'tippy.js/headless'; tippy(targets, { content: 'Hello!', render(instance) { // The recommended structure is to use the popper as an outer wrapper // element, with an inner `box` element const popper = document.createElement('div'); const box = document.createElement('div'); popper.appendChild(box); box.className = 'my-custom-class'; box.textContent = instance.props.content; function onUpdate(prevProps, nextProps) { // DOM diffing if (prevProps.content !== nextProps.content) { box.textContent = nextProps.content; } } // Return an object with two properties: // - `popper` (the root popper element) // - `onUpdate` callback whenever .setProps() or .setContent() is called return { popper, onUpdate, // optional }; }, }); ``` -------------------------------- ### Implementing material filling effect Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/animations.mdx Requires the animateFill plugin and specific backdrop and animation stylesheets. ```js import tippy, {animateFill} from 'tippy.js'; import 'tippy.js/dist/backdrop.css'; import 'tippy.js/animations/shift-away.css'; tippy(targets, { animateFill: true, plugins: [animateFill], }); ``` -------------------------------- ### Configure default props for default Tippy Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/headless-tippy.mdx Disable animations when using the default import in conjunction with headless mode to ensure proper unmounting. ```js import tippy from 'tippy.js'; // This ensures your tippy will unmount if you haven't yet implemented // animations. tippy.setDefaultProps({animation: false}); ``` -------------------------------- ### Enable Instance Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Re-enables a previously disabled tooltip instance. ```js instance.enable(); ``` -------------------------------- ### Initialize tooltips with CSS selector Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/creating-tooltips.mdx Call the tippy function with a CSS selector to target elements with the data-tippy-content attribute. ```js tippy('[data-tippy-content]'); ``` -------------------------------- ### Using onShow Lifecycle Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/ajax.mdx Hook into the onShow event to trigger logic when the tooltip appears. ```js tippy('#ajax-tippy', { content: 'Loading...', flipOnUpdate: true, onShow(instance) { // Code here is executed every time the tippy shows }, }); ``` -------------------------------- ### onMount hook Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/lifecycle-hooks.mdx Executes when the tippy element is mounted to the DOM. ```js tippy(reference, { onMount(instance) { // ... }, }); ``` -------------------------------- ### Importing CSS for animateFill plugin Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/plugins.mdx Required stylesheets for the animateFill plugin. ```js import 'tippy.js/dist/backdrop.css'; import 'tippy.js/animations/shift-away.css'; ``` -------------------------------- ### instance.setContent() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Shortcut method to update the content prop. ```APIDOC ### instance.setContent(content) #### Description Updating the content prop has its own method as a shortcut. #### Parameters - **content** (string|element) - Required - The new content to set. ``` -------------------------------- ### Enable sticky plugin Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md The sticky functionality now requires explicit plugin registration. ```js import tippy, {sticky} from 'tippy.js'; tippy('button', { sticky: true, plugins: [sticky], }); ``` -------------------------------- ### instance.hide() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Programmatically hide the tippy instance. ```APIDOC ### instance.hide(duration?) #### Description Programmatically hide the tippy at any time. #### Parameters - **duration** (number) - Optional - Transition duration in milliseconds. ``` -------------------------------- ### content Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx The content to be displayed inside the tippy. ```APIDOC ## content ### Description The content of the tippy. Can be a string, an Element, or a function returning a string or Element. ### Usage - **content** (string | Element | Function) - Default: '' ### Note To render strings as HTML, set `allowHTML: true`. ``` -------------------------------- ### Set default props globally Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/customizing-tooltips.mdx Use tippy.setDefaultProps() to apply configuration settings to every new tooltip instance created. ```js tippy.setDefaultProps({delay: 50}); ``` -------------------------------- ### Tippy.js Configuration Props Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/all-props.mdx A comprehensive list of properties that can be passed to the tippy() function to configure tooltip behavior and appearance. ```APIDOC ## Tippy.js Configuration Props ### allowHTML (boolean) - Default: true - Description: Determines if content strings are parsed as HTML instead of text. Ensure user data is sanitized to prevent XSS. ### animateFill (boolean) - Default: false - Description: Determines if the background fill color of the tippy should be animated. Requires importing backdrop.css and shift-away.css. ### animation (string) - Default: "fade" - Description: The type of transition animation used for the tooltip. ### appendTo (string | Element | Function) - Default: document.body - Description: The element to append the tippy to. Can be "parent", an Element, or a function returning an Element. ### aria (string | null) - Default: "describedby" - Description: The aria-* attribute applied to the reference element. Options: "describedby", "labelledby", or null. ### arrow (boolean | string | SVGElement) - Default: true - Description: Determines if the tippy has an arrow. Can be a boolean, an SVG string, or an SVGElement. ### boundary (string | HTMLElement) - Default: "scrollParent" - Description: The boundary that Popper.js' preventOverflow modifier adheres to. Options: "scrollParent", "window", "viewport", or an HTMLElement. ``` -------------------------------- ### Show specific child instances Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/addons.mdx The show method accepts indices, reference elements, or specific instances to display. ```js // Show first child tippy instance if no parameter given singleton.show(); // Show given child tippy instance singleton.show(tippyInstances[1]); // Show child tippy instance related to given reference element singleton.show(document.querySelector('button')); // Show child tippy instance at given index singleton.show(2); // i.e equivalent to passing tippyInstances[2] ``` -------------------------------- ### Fetching Content with Fetch API Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/ajax.mdx Perform an AJAX request and update the tooltip content using setContent. ```js tippy('#ajax-tippy', { // ... onShow(instance) { fetch('https://unsplash.it/200/?random') .then((response) => response.blob()) .then((blob) => { // Convert the blob into a URL const url = URL.createObjectURL(blob); // Create an image const image = new Image(); image.width = 200; image.height = 200; image.style.display = 'block'; image.src = url; // Update the tippy content with the image instance.setContent(image); }) .catch((error) => { // Fallback if the network request failed instance.setContent(`Request failed. ${error}`); }); }, }); ``` -------------------------------- ### Configure Inline Positioning Styles Source: https://github.com/atomiks/tippyjs/blob/master/test/visual/index.html Sets layout constraints and visual outlines for inline positioning test elements. ```css #inlinePositioning .wrapper { max-width: 300px; } #inlinePositioning [class^='reference'] { color: white; outline: 1px solid black; } ``` -------------------------------- ### Importing a built-in theme Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/themes.mdx Import the required CSS file for a built-in theme before usage. ```js import 'tippy.js/themes/light.css'; ``` -------------------------------- ### Updating Tooltip Props Dynamically Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/faq.mdx Use the setProps method to update instance configuration after initialization. ```js const instance = tippy(element, {theme: 'custom-dark'}); // When clicking the theme toggle button, you can do this: instance.setProps({theme: 'custom-light'}); ``` -------------------------------- ### Update instance.set() to instance.setProps() Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Replaces the deprecated instance.set method with setProps. ```diff - instance.set({}); + instance.setProps({}); ``` -------------------------------- ### Using plugins via CDN Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/plugins.mdx Standard usage of included plugins in a CDN environment. ```js tippy(targets, { followCursor: true, }); ``` -------------------------------- ### Customize singleton transition timing Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/addons.mdx Modify the transition timing function via the onCreate hook. ```javascript createSingleton(tippyInstances, { updateDuration: 500, onCreate({popper}) { // Any easing function you want. popper.style.transitionTimingFunction = 'cubic-bezier(...)'; }, }); ``` -------------------------------- ### Configure inertia animation Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Enables a spring-like animation for transitions. Higher show durations are recommended for better visual results. ```js tippy(targets, { // default inertia: false, // enable it inertia: true, }); ``` ```css .tippy-box[data-inertia][data-state='visible'] { transition-timing-function: cubic-bezier(...); } ``` ```jsx ``` -------------------------------- ### Enable animateFill effect Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Requires importing specific CSS files and the animateFill plugin. ```js import tippy, {animateFill} from 'tippy.js'; import 'tippy.js/dist/tippy.css'; // These stylesheets are required for it to work import 'tippy.js/dist/backdrop.css'; import 'tippy.js/animations/shift-away.css'; tippy(targets, { animateFill: true, plugins: [animateFill], }); ``` ```html ``` -------------------------------- ### Lifecycle Hooks Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Lifecycle hooks allow you to execute code at specific points in the tippy instance's lifecycle, such as creation, mounting, showing, hiding, and destruction. ```APIDOC ## Lifecycle Hooks ### Description Lifecycle hooks are functions provided in the configuration object that are invoked during specific stages of the tippy instance's lifecycle. ### Available Hooks - **onCreate(instance)**: Invoked once the tippy has been created. - **onDestroy(instance)**: Invoked once the tippy has been destroyed. - **onHidden(instance)**: Invoked once the tippy has been fully hidden and unmounted. - **onHide(instance)**: Invoked once the tippy begins to hide. Returning `false` cancels the hide. - **onMount(instance)**: Invoked once the tippy has been mounted to the DOM. - **onShow(instance)**: Invoked once the tippy begins to show. Returning `false` cancels the show. - **onShown(instance)**: Invoked once the tippy has fully transitioned in. - **onTrigger(instance, event)**: Invoked when triggered by a DOM event. - **onUntrigger(instance, event)**: Invoked when untriggered by a DOM event. ``` -------------------------------- ### Enable Interactivity Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Allows users to interact with the tooltip content, such as selecting text. ```js tippy(button, { interactive: true, }); ``` -------------------------------- ### Migrate tippy.group to createSingleton Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Replaces the deprecated tippy.group method with createSingleton. ```js import tippy, {createSingleton} from 'tippy.js'; createSingleton(tippy('button'), {delay: 1000}); ``` ```html ``` -------------------------------- ### Configure appendTo Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Specifies the DOM element where the tooltip is appended. ```js tippy(targets, { // default (takes reference as an argument) appendTo: () => document.body, // append to reference's parentNode appendTo: 'parent', // append to an Element appendTo: element, }); ``` -------------------------------- ### Implementing Virtual Elements Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Use getReferenceClientRect to implement Popper 2's Virtual Elements API instead of manual popperInstance manipulation. ```js tippy(targets, { lazy: false, onCreate(instance) { instance.popperInstance.reference = { clientWidth: 0, clientHeight: 0, getBoundingClientRect() { return { // ... }; }, }; }, }); ``` ```js tippy(targets, { getReferenceClientRect: () => ({ // ... }), }); ``` -------------------------------- ### Popper Options Configuration Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Provides full control over positioning by passing custom options to Popper.js. ```js tippy(targets, { // default popperOptions: {}, // detailed example popperOptions: { strategy: 'fixed', modifiers: [ { name: 'flip', options: { fallbackPlacements: ['bottom', 'right'], }, }, { name: 'preventOverflow', options: { altAxis: true, tether: false, }, }, ], }, }); ``` -------------------------------- ### Render HTML string in tooltip Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/html-content.mdx Use allowHTML: true to render HTML strings. Sanitize user-provided content to prevent XSS. ```js tippy('button', { content: 'Bolded content', allowHTML: true, }); ``` -------------------------------- ### Lifecycle Hooks Configuration Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/lifecycle-hooks.mdx A collection of lifecycle hooks that can be defined in the tippy configuration object to intercept instance events. ```APIDOC ## Lifecycle Hooks ### onCreate(instance) Executed once when the tippy is first created. ### onTrigger(instance, event) Executed when the tippy is triggered by a DOM event, before it starts to show. ### onShow(instance) Executed when the tippy begins to show, before mounting to the DOM. Returning `false` cancels the show action. ### onMount(instance) Executed when the tippy element is mounted to the DOM. ### onShown(instance) Executed when the tippy has fully transitioned in. ### onUntrigger(instance, event) Executed when the tippy is untriggered by a DOM event, before it starts to hide. ### onHide(instance) Executed when the tippy begins to hide and transition out. Returning `false` cancels the hide action. ### onHidden(instance) Executed when the tippy has fully transitioned out and unmounted from the DOM. ### onBeforeUpdate(instance, updatedProps) Executed before a tippy's props are updated via `.setContent()` or `.setProps()`. ### onAfterUpdate(instance, updatedProps) Executed after a tippy's props are updated via `.setContent()` or `.setProps()`. ### onDestroy(instance) Executed once when the tippy is destroyed. ``` -------------------------------- ### Render HTML via element innerHTML Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/html-content.mdx Use an existing DOM element's innerHTML to populate the tooltip content. ```html ``` ```js const template = document.getElementById('template'); tippy('button', { content: template.innerHTML, }); ``` -------------------------------- ### Render HTML Content Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Enables rendering of HTML strings within the tooltip. ```js tippy(button, { content: 'Bolded content', allowHTML: true, }); ``` -------------------------------- ### Configure allowHTML Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Controls whether content strings are parsed as HTML. Ensure user data is sanitized to prevent XSS. ```js tippy(targets, { // default allowHTML: false, // parse `content` strings as HTML allowHTML: true, }); ``` -------------------------------- ### Lifecycle hooks Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Event handlers for updating and interacting with the tippy instance. ```js tippy(targets, { onAfterUpdate(instance, partialProps) { // ... }, }); ``` ```js tippy(targets, { onBeforeUpdate(instance, partialProps) { // ... }, }); ``` ```js tippy(targets, { onClickOutside(instance, event) { // ... }, }); ``` -------------------------------- ### Configure smooth transitions Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/addons.mdx Use the moveTransition prop to define the CSS transition for position updates. ```js const singleton = createSingleton(tippyInstances, { delay: 1000, moveTransition: 'transform 0.2s ease-out', }); ``` -------------------------------- ### Use Injected CSS Bundle Source: https://github.com/atomiks/tippyjs/blob/master/MIGRATION_GUIDE.md Opt-in to the v4-style behavior where CSS is automatically injected by using the bundle import. ```javascript // Just like v4 import tippy from 'tippy.js/dist/tippy-bundle.esm'; // Or CommonJS: const tippy = require('tippy.js/dist/tippy-bundle.cjs'); ``` -------------------------------- ### instance.unmount() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/methods.mdx Unmount the tippy from the DOM. ```APIDOC ## instance.unmount() ### Description Unmount the tippy from the DOM. ``` -------------------------------- ### Customize tooltips with configuration object Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/customizing-tooltips.mdx Pass an object of optional props as the second argument to the tippy() function to customize tooltip behavior. ```js tippy('button', { duration: 0, arrow: false, delay: [1000, 200], }); ``` -------------------------------- ### Lifecycle Hooks Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Hooks for handling tippy lifecycle events like updates and clicks. ```APIDOC ## Lifecycle Hooks ### onAfterUpdate Invoked after the tippy has been updated (via `.setProps()`). ### onBeforeUpdate Invoked before the tippy has been updated (via `.setProps()`). ### onClickOutside Invoked when the user clicks anywhere outside of the tippy or reference element. ``` -------------------------------- ### Hide Instance Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Triggers the tooltip to hide, optionally specifying a transition duration in milliseconds. ```js instance.hide(); // Default instance.hide(500); // 500ms transition duration ``` -------------------------------- ### Placement Configuration Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Defines the preferred placement of the tippy relative to the reference element. ```js tippy(targets, { // default placement: 'top', // full list: placement: 'top-start', placement: 'top-end', placement: 'right', placement: 'right-start', placement: 'right-end', placement: 'bottom', placement: 'bottom-start', placement: 'bottom-end', placement: 'left', placement: 'left-start', placement: 'left-end', // choose the side with most space placement: 'auto', placement: 'auto-start', placement: 'auto-end', }); ``` -------------------------------- ### Configure trigger events Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Specifies the events that trigger the tippy. Multiple events can be separated by spaces. ```js tippy(targets, { // default trigger: 'mouseenter focus', // others: trigger: 'click', trigger: 'focusin', trigger: 'mouseenter click', // only programmatically trigger it trigger: 'manual', }); ``` -------------------------------- ### instance.setProps() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Update any prop after the instance has been created. ```APIDOC ### instance.setProps(props) #### Description Update any prop after the instance has been created. #### Parameters - **props** (object) - Required - An object of new props to apply. ``` -------------------------------- ### Import Tippy.js in Module Bundlers Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/getting-started.mdx Import the module and core CSS when using bundlers like webpack, Rollup, or Parcel. ```javascript import tippy from 'tippy.js'; import 'tippy.js/dist/tippy.css'; // optional for styling ``` -------------------------------- ### instance.destroy() Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Permanently destroy and clean up the instance. ```APIDOC ### instance.destroy() #### Description To permanently destroy and clean up the instance, use this method. The _tippy property is deleted from the reference element upon destruction. ``` -------------------------------- ### Accessing instance via _tippy property Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/tippy-instance.mdx Retrieve an instance from a reference or popper element using the _tippy property. ```js const button = document.querySelector('button'); tippy(button); const instance = button._tippy; ``` -------------------------------- ### Set transition delays Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Configures the delay in milliseconds before the tippy shows or hides after a trigger event. ```js tippy(targets, { // default delay: 0, // show and hide delay are 100ms delay: 100, // show delay is 100ms, hide delay is 200ms delay: [100, 200], // show delay is 100ms, hide delay is the default delay: [100, null], }); ``` -------------------------------- ### onShown hook Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/lifecycle-hooks.mdx Executes after the tippy has fully transitioned in. ```js tippy(reference, { onShown(instance) { // ... }, }); ``` -------------------------------- ### Importing the border stylesheet Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/themes.mdx Include this stylesheet to enable border color inheritance and support for SVG arrow borders. ```js import 'tippy.js/dist/border.css'; ``` -------------------------------- ### Configure animateFill Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/all-props.mdx Enables or disables the animated background fill effect. ```js tippy(targets, { // default animateFill: false, // enable it animateFill: true, }); ``` ```js import tippy, {animateFill} from 'tippy.js'; import 'tippy.js/dist/backdrop.css'; import 'tippy.js/animations/shift-away.css'; tippy(targets, { animateFill: true, plugins: [animateFill], }); ``` -------------------------------- ### Update Instance Content Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/methods.mdx Shortcut method for updating the content property of an instance. ```js instance.setContent('New content'); ``` -------------------------------- ### Enabling inertia Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/animations.mdx Set the inertia prop to true to add elastic physics-like effects. ```js tippy('button', { inertia: true, }); ``` -------------------------------- ### Link templates dynamically Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/html-content.mdx Use a function for the content prop to return specific template content based on the reference element's attributes. ```html
Content for `one`
Content for `two`
Content for `three`
``` ```js tippy('button', { content(reference) { const id = reference.getAttribute('data-template'); const template = document.getElementById(id); return template.innerHTML; }, }); ``` -------------------------------- ### Using CSS animations Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v6/animations.mdx Apply CSS classes during the onMount and onHidden lifecycle hooks to trigger external animations. ```js tippy('button', { onMount(instance) { const box = instance.popper.firstElementChild; requestAnimationFrame(() => { box.classList.add('animated'); box.classList.add('wobble'); }); }, onHidden(instance) { const box = instance.popper.firstElementChild; box.classList.remove('animated'); box.classList.remove('wobble'); }, }); ``` -------------------------------- ### Importing SVG arrow styles Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/themes.mdx Import the SVG arrow stylesheet to enable SVG arrow styling. ```js import 'tippy.js/dist/svg-arrow.css'; ``` -------------------------------- ### Using CSS animations Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/animations.mdx Manually toggle CSS classes on mount and hidden hooks to trigger animations. ```js tippy('button', { onMount(instance) { const {tooltip} = instance.popperChildren; requestAnimationFrame(() => { tooltip.classList.add('animated'); tooltip.classList.add('wobble'); }); }, onHidden(instance) { const {tooltip} = instance.popperChildren; tooltip.classList.remove('animated'); tooltip.classList.remove('wobble'); }, }); ``` -------------------------------- ### Configuring Rollup Environment Variables Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/faq.mdx Use the replace plugin to define environment variables for production or development builds. ```js import replace from 'rollup-plugin-replace'; export default { // ... plugins: [ // Production config replace({ 'process.env.NODE_ENV': JSON.stringify('production'), }), // OR development config replace({ 'process.env.NODE_ENV': JSON.stringify('development'), }), // You can also use process.env.NODE_ENV and set the env variables when // running the rollup command to merge the above into one call ], }; ``` -------------------------------- ### Applying a custom animation Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/animations.mdx Reference the custom animation name in the configuration object. ```js tippy('button', { animation: 'rotate', }); ``` -------------------------------- ### Importing built-in animations Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/v5/animations.mdx Import the required CSS file for the desired animation before usage. ```js import 'tippy.js/animations/scale.css'; ``` -------------------------------- ### Configure Trigger Source: https://github.com/atomiks/tippyjs/blob/master/website/src/pages/index.mdx Defines the event that triggers the tooltip display. ```js tippy(button, { // default trigger: 'click', }); ```