@tippyjs/react

What is @tippyjs/react?

@tippyjs/react is a React wrapper for Tippy.js, a highly customizable tooltip and popover library. It allows you to create tooltips, popovers, dropdowns, and more with ease, providing a wide range of customization options and animations.

What are @tippyjs/react's main functionalities?

Basic Tooltip

This feature allows you to create a basic tooltip that appears when you hover over an element. The tooltip content is customizable.

import Tippy from '@tippyjs/react';
import 'tippy.js/dist/tippy.css';

function App() {
  return (
    <Tippy content="Hello, World!">
      <button>Hover me</button>
    </Tippy>
  );
}

Interactive Tooltip

This feature allows you to create an interactive tooltip that can contain HTML content and can be interacted with.

import Tippy from '@tippyjs/react';
import 'tippy.js/dist/tippy.css';

function App() {
  return (
    <Tippy content={<span>Interactive Content</span>} interactive={true}>
      <button>Hover me</button>
    </Tippy>
  );
}

Custom Animation

This feature allows you to add custom animations to your tooltips. Tippy.js provides several built-in animations that you can use.

import Tippy from '@tippyjs/react';
import 'tippy.js/animations/scale.css';

function App() {
  return (
    <Tippy content="Animated Tooltip" animation="scale">
      <button>Hover me</button>
    </Tippy>
  );
}

Controlled Tooltip

This feature allows you to control the visibility of the tooltip programmatically, giving you more control over when the tooltip appears and disappears.

import Tippy from '@tippyjs/react';
import 'tippy.js/dist/tippy.css';
import { useState } from 'react';

function App() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <button onClick={() => setVisible(!visible)}>Toggle Tooltip</button>
      <Tippy content="Controlled Tooltip" visible={visible}>
        <button>Hover me</button>
      </Tippy>
    </>
  );
}

Other packages similar to @tippyjs/react

react-tooltip

react-tooltip is another popular tooltip library for React. It provides a simple API for creating tooltips with various customization options. Compared to @tippyjs/react, it is less feature-rich but easier to set up for basic use cases.

react-popper

react-popper is a React wrapper for Popper.js, a library used to position tooltips and popovers. It provides more control over positioning and is highly customizable, but it requires more setup compared to @tippyjs/react.

react-bootstrap

react-bootstrap is a popular UI library for React that includes a Tooltip component. It is a good choice if you are already using Bootstrap in your project, but it is less customizable compared to @tippyjs/react.

README

Tippy.js for React

Tippy.js is the complete tooltip, popover, dropdown, and menu solution for the web, powered by Popper.js.

It is an abstraction over Popper that provides the logic and optionally the styling involved in all types of elements that pop out from the flow of the document and get overlaid on top of the UI, positioned next to a reference element.

This is a lightweight wrapper that lets you use it declaratively in React, providing full integration including headless rendering abilities. Tippy has virtually no restrictions over Popper, and gives you limitless control while providing useful behavior and defaults.

🚀 Installation

# npm
npm i @tippyjs/react

# Yarn
yarn add @tippyjs/react

CDN: https://unpkg.com/@tippyjs/react

Requires React 16.8+

🖲 Usage

There are two ways to use this component:

• Default: With the built-in DOM rendering and optionally the default CSS. This is complete "out of the box" behavior and requires no setup. If you want something that just works, this is for you.
• Headless: With React's DOM rendering for improved usage with CSS-in-JS and spring libraries. If you want greater control over your poppers to integrate fully with design systems, this is for you.

You can use both of these in conjunction if you'd like though — if so, use the default import and set animation={false} as a default prop instead of using the /headless import.

Default Tippy

Import the Tippy component and (optionally) the core CSS. Wrap the <Tippy /> component around the element, supplying the tooltip's content as the content prop. It can take a string or a tree of React elements.

import React from 'react';
import Tippy from '@tippyjs/react';
import 'tippy.js/dist/tippy.css'; // optional

const StringContent = () => (
  <Tippy content="Hello">
    <button>My button</button>
  </Tippy>
);

const JSXContent = () => (
  <Tippy content={<span>Tooltip</span>}>
    <button>My button</button>
  </Tippy>
);

Default Tippy is very quick to use and setup and "just works" out of the box.

Headless Tippy

Render your own tippy element from scratch:

import React from 'react';
import Tippy from '@tippyjs/react/headless';

const HeadlessTippy = () => (
  <Tippy
    render={attrs => (
      <div className="box" tabIndex="-1" {...attrs}>
        My tippy box
      </div>
    )}
  >
    <button>My button</button>
  </Tippy>
);

attrs is an object containing data-placement, data-reference-hidden, and data-escaped attributes. This allows you to conditionally style your tippy if necessary.

Headless animation

• framer-motion
• react-spring

Arrow

To make Popper position your custom arrow, set a data-popper-arrow attribute on it:

<Tippy
  render={attrs => (
    <Box {...attrs}>
      Hello
      <Arrow data-popper-arrow="" />
    </Box>
  )}
>
  <button>Reference</button>
</Tippy>

For details on styling the arrow from scratch, take a look at the Popper tutorial.

Note: your arrow must be an HTMLElement (not an SVGElement). To use an SVG arrow, wrap it in a <div> tag with the data-popper-arrow attribute.

You may also pass a ref to the element directly without the attribute using a callback ref:

function App() {
  const [arrow, setArrow] = useState(null);

  return (
    <Tippy
      render={attrs => (
        <Box {...attrs}>
          Content
          <Arrow ref={setArrow} />
        </Box>
      )}
      popperOptions={{
        modifiers: [
          {
            name: 'arrow',
            options: {
              element: arrow, // can be a CSS selector too
            },
          },
        ],
      }}
    >
      <button>Reference</button>
    </Tippy>
  );
}

Note on Headless Tippy in React

The root popper node is abstracted away and gets styled/mutated by Tippy internally, so Headless Tippy in React is partially headless. This ensures it works correctly with minimal effort on your behalf to render.

When rendering an element with the render prop, you're rendering the inner box element that the root popper node wraps, which is what gets styled and animated. For advanced cases, you can access the parent popper node as instance.popper in the onCreate lifecycle hook.

Here's moveTransition with Framer Motion.

Component children

If you want to use a component element as a child, ensure you forward the ref to the DOM node:

import React, {forwardRef} from 'react';

function ThisWontWork() {
  return <button>Reference</button>;
}

const ThisWillWork = forwardRef((props, ref) => {
  return <button ref={ref}>Reference</button>;
});

function App() {
  return (
    <Tippy content="Tooltip">
      <ThisWillWork />
    </Tippy>
  );
}

styled-components v4+ does this for you automatically, so it should be seamless when using the styled constructor.

If you're using a library that doesn't forwardRef for you, and doesn't give access to the ref via innerRef or similar, you can use a wrapper <span> element as a workaround.

<Tippy content="Tooltip">
  <span tabIndex="0">
    <LegacyComponent>Reference</LegacyComponent>
  </span>
</Tippy>

🧬 Props

All of the native Tippy.js props can be passed to the component.

Visit All Props to view the complete list.

<Tippy
  content="Tooltip"
  interactive={true}
  interactiveBorder={20}
  delay={100}
  // ...and many more!
>
  <button>Reference</button>
</Tippy>

In addition, there are 3 more props added specifically for the React component.

className?: string

Note: This does not apply if using Headless Tippy, as you can set this on the element yourself.

A React alternative to the theme prop. The className gets added to the tooltip element's class list as expected, without adding -theme as a suffix.

<Tippy content="Tooltip" className="hello world">
  <button>Reference</button>
</Tippy>

If you're using styled-components, the className prop allows you to avoid global styles with the following technique:

const PurpleTippy = styled(Tippy)`
  background: purple;

  /* Styling the arrow for different placements */
  &[data-placement^='top'] > .tippy-arrow::before {
    border-top-color: purple;
  }
`;

See themes for more information.

disabled?: boolean

function App() {
  const [disabled, setDisabled] = useState(false);

  return (
    <Tippy content="Tooltip" disabled={disabled}>
      <button>Reference</button>
    </Tippy>
  );
}

visible?: boolean (controlled mode)

Use React's state to fully control the tippy instead of relying on the native trigger and hideOnClick props:

function App() {
  const [visible, setVisible] = useState(true);
  const show = () => setVisible(true);
  const hide = () => setVisible(false);

  return (
    <Tippy content="Tooltip" visible={visible} onClickOutside={hide}>
      <button onClick={visible ? hide : show}>Reference</button>
    </Tippy>
  );
}

Plugins

Tippy.js splits certain props into separate pieces of code called plugins to enable tree-shaking, so that components or routes that don't need the prop's functionality are not burdened with the bundle size cost of it. In addition, they enable a neat way to extend the functionality of tippy instances.

import Tippy from '@tippyjs/react';
// ⚠️ import from 'tippy.js/headless' if using Headless Tippy
import {followCursor} from 'tippy.js';

function App() {
  return (
    <Tippy content="Tooltip" followCursor={true} plugins={[followCursor]}>
      <button>Reference</button>
    </Tippy>
  );
}

Read more about plugins here.

🌈 Multiple tippies on a single element

You can nest the components like so:

<Tippy content="Tooltip" placement="bottom">
  <Tippy content="Tooltip" placement="left">
    <Tippy content="Tooltip" placement="right">
      <Tippy content="Tooltip">
        <button>Reference</button>
      </Tippy>
    </Tippy>
  </Tippy>
</Tippy>

Lazy mounting

By default, Tippy mounts your content or render elements into a container element once created, even if the tippy isn't mounted on the DOM. In most cases, this is fine, but in performance-sensitive scenarios or cases where mounting the component should fire effects only when the tippy mounted, you can lazify the component.

View the following gists to optimize your <Tippy /> if needed.

📚 useSingleton

A Hook for the createSingleton() addon to re-use a single tippy element for many different reference element targets.

View on CodeSandbox

import Tippy, {useSingleton} from '@tippyjs/react';

function App() {
  const [source, target] = useSingleton();

  return (
    <>
      {/* This is the tippy that gets used as the singleton */}
      <Tippy singleton={source} delay={500} />

      {/* These become "virtual" */}
      <Tippy content="Hello" singleton={target}>
        <button>Reference</button>
      </Tippy>
      <Tippy content="Bye" singleton={target}>
        <button>Reference</button>
      </Tippy>
    </>
  );
}

useSingleton() takes an optional props argument:

const [source, target] = useSingleton({
  disabled: true,
  overrides: ['placement'],
});

Headless singleton

The render prop takes the singleton content as a second parameter:

import Tippy, {useSingleton} from '@tippyjs/react/headless';

function App() {
  const [source, target] = useSingleton();

  return (
    <>
      <Tippy
        singleton={source}
        render={(attrs, content) => (
          <div className="box" tabIndex="-1" {...attrs}>
            {content}
          </div>
        )}
        delay={500}
      />

      <Tippy content="Hello" singleton={target}>
        <button>Reference</button>
      </Tippy>
      <Tippy content="Bye" singleton={target}>
        <button>Reference</button>
      </Tippy>
    </>
  );
}

📝 License

MIT