@tippyjs/react
v4.2.6TypeScript
React component for Tippy.js
868.7K/weekUpdated 3 years agoMITUnpacked: 262.9 KB
Published by atomiks
npm install @tippyjs/react
Tippy.js for React
Tippy.js is the complete tooltip,
popover, dropdown, and menu solution for the web, powered by Popper.
Tippy is an abstraction over Popper that provides common logic involved in all
types of elements that pop out on top of the UI, positioned next to a target or
reference element. This is a React wrapper for the core library, providing full
integration including headless rendering abilities.
🚀 Installation
``bashnpm
npm i @tippyjs/react
Yarn
yarn add @tippyjs/react
`
CDN: https://unpkg.com/@tippyjs/react
🖲 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.
Both may be used in conjunction.
$3
Import the
component and (optionally) the core CSS. Wrap the
component around the element, supplying the tooltip's content as the
prop. It can take a string or a tree of React elements.jsx
import React from 'react';
import Tippy from '@tippyjs/react';
import 'tippy.js/dist/tippy.css'; // optionalconst StringContent = () => (
);
const JSXContent = () => (
Tooltip}>
);
`Default Tippy "just works" out of the box.
$3
Render your own tippy element from scratch:
jsx
import React from 'react';
import Tippy from '@tippyjs/react/headless'; // different import path!const HeadlessTippy = () => (
My tippy box
)}
>
);
` is an object containing data-placement, data-reference-hidden, and
data-escaped attributes. This allows you to conditionally style your tippy.#### Headless animation
framer-motion
- #### Headless arrow
To make Popper position your custom arrow, set a
attribute
on it:`jsx
Hello
)}
>
`For details on styling the arrow from scratch,
take a look at the Popper tutorial.
**Note: your arrow must be an
(not an SVGElement). To use an SVG
arrow, wrap it in a tag with the data-popper-arrow attribute.**You may also pass a ref to the element directly without the attribute using a
callback ref:
`jsx
function App() {
const [arrow, setArrow] = useState(null); return (
Content
)}
popperOptions={{
modifiers: [
{
name: 'arrow',
options: {
element: arrow, // can be a CSS selector too
},
},
],
}}
>
);
}
`#### Headless root element
When rendering an element with the
prop, you're rendering the inner
element that the root popper (positioned) node wraps.For advanced cases you can access the root element via
instance.popper.moveTransition with Framer Motion.$3
If you want to use a component element as a child of the component, ensure you
forward the ref to the DOM node:
`jsx
import React, {forwardRef} from 'react';function ThisWontWork() {
return ;
}
const ThisWillWork = forwardRef((props, ref) => {
return ;
});
function App() {
return (
);
}
` v4+ does this for you automatically, so it should be
seamless when using the styled constructor.Workaround for old libraries that don't forward the ref is to use a
wrapper tag:jsx
Reference
`🧬 Props
All of the native Tippy.js props can be passed to the component.
Visit All Props to view the
complete list.
jsx
`In addition, there are 3 more props added specifically for the React component.
$3
jsx
`This allows you to use
or the css prop in styled-components
or .> Note: Does not apply if using Headless Tippy.
$3
`jsx
function App() {
const [disabled, setDisabled] = useState(false); return (
);
}
`$3
Use React's state to fully control the tippy instead of relying on the native
and hideOnClick props:`jsx
function App() {
const [visible, setVisible] = useState(true);
const show = () => setVisible(true);
const hide = () => setVisible(false); return (
);
}
`$3
> Available from
If you can't place your reference element as a child inside
, you can
use this prop instead. It accepts a React RefObject (.current property) or a
plain Element.`jsx
function App() {
const ref = useRef(); return (
<>
);
}
`$3
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.
jsx
import Tippy from '@tippyjs/react';
// ⚠️ import from 'tippy.js/headless' if using Headless Tippy
import {followCursor} from 'tippy.js';function App() {
return (
);
}
`🌈 Multiple tippies on a single element
You can nest the components like so:
jsx
`Lazy mounting
By default, Tippy mounts your
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. if needed.📚 useSingleton
createSingleton()
addon to re-use a single tippy element for many different reference element
targets.jsx
import Tippy, {useSingleton} from '@tippyjs/react';function App() {
const [source, target] = useSingleton();
return (
<>
{/ This is the tippy that gets used as the singleton /}
{/ These become "virtual" /}
);
}
` takes an optional props argument:`js
const [source, target] = useSingleton({
disabled: true,
overrides: ['placement'],
});
`$3
The
prop takes the singleton content as a second parameter:`jsx
import Tippy, {useSingleton} from '@tippyjs/react/headless';function App() {
const [source, target] = useSingleton();
return (
<>
render={(attrs, content) => (
{content}
)}
delay={500}
/>
);
}
``📝 License
MIT