Skip to content
Official React component for Tippy.js
Branch: master
Clone or download
atomiks Remove need for explicit multiple prop (#72)
* Remove need for explicit multiple prop

* ...nativeProps → ...restOfNativeProps
Latest commit 6ebc397 Mar 24, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo Fix server warning for useLayoutEffect (#59) Feb 24, 2019
src Remove need for explicit multiple prop (#72) Mar 23, 2019
test
.babelrc
.eslintrc
.gitignore
.prettierrc Formatting & linting setup (#43) Jan 22, 2019
LICENSE
README.md
index.d.ts tip → instance Mar 13, 2019
logo.png
package-lock.json
package.json Use unpkg field with unminified in main field Mar 11, 2019
rollup.build.js Build from index.js Feb 12, 2019
tsconfig.json V2 (#46) Feb 9, 2019

README.md

Logo

Tippy.js for React

npm Downloads per Month MIT License

The complete tooltip and popover solution for React apps

Tippy.js is a highly customizable tooltip and popover library powered by Popper.js. This is a lightweight wrapper that lets you use it declaratively in React.

🚀 Installation

# npm
npm i @tippy.js/react

# Yarn
yarn add @tippy.js/react

CDN: https://unpkg.com/@tippy.js/react

Requires React 16.8+

🖲 Usage

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 '@tippy.js/react'

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

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

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>Text</button>
}

const ThisWillWork = forwardRef((props, ref) => {
  return <button ref={ref}>Text</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>
    <LegacyComponent>Unfortunately</LegacyComponent>
  </span>
</Tippy>

Although Tippy will add tabindex for you on the <span> which allows it to receive focus, it may affect accessibility with regards to screenreaders, since <span> is not traditionally focusable (unlike a <button> for example).

🧬 Props

All of the native Tippy.js options can be passed as props.

Visit All Options to view the complete table.

<Tippy
  content="Tooltip"
  arrow={true}
  animation="scale"
  duration={0}
  delay={[300, 0]}
  // ...and many more!
>
  <button>Text</button>
</Tippy>

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

className?: string (v2.1)

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 />
</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 */
  &[x-placement^='top'] {
    .tippy-arrow {
      border-top-color: purple;
    }
  }
`

See themes for more information.

Note: the following examples are using the new React Hooks API. It isn't required to use this library – the props will work as expected in class components too.

isEnabled?: boolean

Prop to control the tippy.enable() / tippy.disable() instance methods. Use this when you want to temporarily disable a tippy from showing.

function App() {
  const [isEnabled, setIsEnabled] = useState(true)
  return (
    <Tippy content="Tooltip" isEnabled={isEnabled}>
      <button />
    </Tippy>
  )
}

isVisible?: boolean

Prop to control the tippy.show() / tippy.hide() instance methods. Use this when you want to programmatically show or hide the tippy instead of relying on UI events. This puts the tippy in controlled mode so it will only respond to state.

function App() {
  const [isVisible, setIsVisible] = useState(true)
  return (
    <Tippy content="Tooltip" isVisible={isVisible}>
      <button />
    </Tippy>
  )
}

Note: You should also set the hideOnClick prop to false if you don't want the tippy to hide when the user clicks on the document somewhere.

onCreate?: (instance: Instance) => void

Callback invoked when the tippy instance has been created. Use this when you need to store the tippy instance on the component.

This should only be done for advanced (imperative) manipulation of the tippy instance – in most cases using props should suffice.

function App() {
  const tippyInstance = useRef()
  return (
    <Tippy
      content="Tooltip"
      onCreate={instance => (tippyInstance.current = instance)}
    >
      <button />
    </Tippy>
  )
}

Default props

You can create a new component file that imports the component and sets the default props. From this file, you can import the component throughout your app.

import Tippy from '@tippy.js/react'

Tippy.defaultProps = {
  ...Tippy.defaultProps,
  arrow: true,
}

export default Tippy

You could also create Proxy components that wrap the base <Tippy /> component with a new name and sets its own default props:

export const Tooltip = props => <Tippy {...props} />
Tooltip.defaultProps = {
  animation: 'fade',
  arrow: true,
  delay: 150,
  theme: 'translucent',
}

export const Popover = props => <Tippy {...props} />
Popover.defaultProps = {
  animateFill: false,
  animation: 'scale',
  interactive: true,
  interactiveBorder: 10,
  theme: 'light-border',
  trigger: 'click',
}

// In another file
import { Tooltip, Popover } from './Tippy'

🌈 Multiple tippys on a single element

You can nest the components, ensuring they have a multiple prop:

<Tippy placement="bottom" multiple>
  <Tippy placement="left" multiple>
    <Tippy placement="right" multiple>
      <Tippy multiple>
        <button />
      </Tippy>
    </Tippy>
  </Tippy>
</Tippy>

📚 <TippyGroup />

Wraps the tippy.group() method.

import Tippy, { TippyGroup } from '@tippy.js/react'

function App() {
  return (
    <TippyGroup delay={1000}>
      <Tippy content="a">
        <button />
      </Tippy>
      <Tippy content="b">
        <button />
      </Tippy>
    </TippyGroup>
  )
}

📦 Bundle size

Bundle size

  • popper.js ≈ 7 kB
  • tippy.js ≈ 7.5 kB (including CSS)
  • @tippy.js/react ≈ 1 kB

If you're using Popper.js for other parts of your app, the added cost becomes much smaller!

⭐️ Comparison with other tooltip/popover libraries

Why should you use this library, and how does it compare to other ones?

Read all about it here!

📝 License

MIT

You can’t perform that action at this time.