React Popper
React wrapper around Popper.
important note: Popper is not a tooltip library, it's a positioning
engine to be used to build features such as (but not restricted to) tooltips.
Install
Via package managers:
npm install react-popper @popperjs/core --save
yarn add react-popper @popperjs/core
Note: @popperjs/core
must be installed in your project in order for
react-popper
to work.
Via script
tag (UMD library exposed as ReactPopper
):
<script src="https://unpkg.com/react-popper/dist/index.umd.js"></script>
Usage
Using react-popper@0.x
? You can find its documentation
clicking here
react-popper
provides two different APIs to help consume it:
React Hooks
The usePopper
hook can be used to quickly initialize a Popper, it requires a
basic understanding of how the
React Hooks work.
import { useState } from 'react';
import { usePopper } from 'react-popper';
const Example = () => {
const [referenceElement, setReferenceElement] = useState(null);
const [popperElement, setPopperElement] = useState(null);
const [arrowElement, setArrowElement] = useState(null);
const { styles, attributes } = usePopper(referenceElement, popperElement, {
modifiers: [{ name: 'arrow', options: { element: arrowElement } }],
});
return (
<>
<button type="button" ref={setReferenceElement}>
Reference element
</button>
<div ref={setPopperElement} style={styles.popper} {...attributes.popper}>
Popper element
<div ref={setArrowElement} style={styles.arrow} />
</div>
</>
);
};
Render Props
The Manager
, Reference
and Popper
render-props components offer an
alternative API to initialize a Popper instance, they require a basic
understanding of how the
React Render Props work.
import { Manager, Reference, Popper } from 'react-popper';
const Example = () => (
<Manager>
<Reference>
{({ ref }) => (
<button type="button" ref={ref}>
Reference element
</button>
)}
</Reference>
<Popper placement="right">
{({ ref, style, placement, arrowProps }) => (
<div ref={ref} style={style} data-placement={placement}>
Popper element
<div ref={arrowProps.ref} style={arrowProps.style} />
</div>
)}
</Popper>
</Manager>
);
API documentation
Hooks
The usePopper
hook provides an API almost identical to the ones of
createPopper
constructor.
Rather than returning a Popper instance, it will return an object containing the
following properties:
styles
The styles
property is an object, its properties are popper
, and arrow
.
The two properties are a
CSSStyleDeclaration
interface
describing the necessary CSS properties needed to properly position the two
elements.
You can directly assign the value of the two properties to the React style
property of your components.
<div style={styles.popper} />
attributes
Similar to styles
, the attributes
object lists the popper
and arrow
HTML
attributes, by default, only popper
will hold some attributes (e.g.
data-popper-placement
), but more generically, any HTML attribute described by
the Popper documentation will be available inside these properties.
The easiest way to consume their values is by destructuring them directly onto
your React component.
<div {...attributes.popper} />
update
, forceUpdate
, and state
These properties match the ones described in the
Popper docs, the only
difference is that they can be null
if Popper isn't yet been initialized or
has been destroyed.
Render Props
The Manager
component is a simple wrapper that needs to surround all the other
react-popper
components in order to make them communicate with each others.
The Popper
component accepts the properties children
, placement
,
modifiers
and strategy
.
<Popper
innerRef={(node) => this.popperNode = node}
placement="right"
modifiers={[{ name: 'preventOverflow', enabled: false }]}
strategy="fixed"
>
{ props => [...] }
</Popper>
children
children: ({|
ref: (?HTMLElement) => void,
style: { [string]: string | number },
placement: ?Placement,
isReferenceHidden: ?boolean,
hasPopperEscaped: ?boolean,
update: () => void,
forceUpdate: () => void,
arrowProps: {
ref: (?HTMLElement) => void,
style: { [string]: string | number },
},
|}) => Node
A function (render prop) that takes as argument an object containing the
following properties:
ref
: used to retrieve the
React refs of the popper
element.style
: contains the necessary CSS styles (React CSS properties) which
are computed by Popper.js to correctly position the popper element.placement
: describes the placement of your popper after Popper.js has
applied all the modifiers that may have flipped or altered the originally
provided placement
property. You can use this to alter the style of the
popper and or of the arrow according to the definitive placement. For
instance, you can use this property to orient the arrow to the right
direction.isReferenceHidden
: a boolean signifying the reference element is fully
clipped and hidden from view.hasPopperEscaped
: a boolean signifying the popper escapes the reference
element's boundary (and so it appears detached).update
: a function you can ask Popper to recompute your tooltip's
position . It will directly call the
Popper#update
method.arrowProps
: an object, containing style
and ref
properties that are
identical to the ones provided as the first and second arguments of
children
, but relative to the arrow element. The style
property
contains left
and top
offset values, which are used to center the arrow
within the popper. These values can be merged with further custom styling and
positioning. See
the demo
for an example.
innerRef
innerRef?: (?HTMLElement) => void
Function that can be used to obtain popper reference
placement
placement?: PopperJS$Placement;
One of the accepted placement values listed in the
Popper.js documentation.
Your popper is going to be placed according to the value of this property.
Defaults to bottom
.
strategy
Describes the positioning strategy to use. By default, it is absolute
, which
in the simplest cases does not require repositioning of the popper. If your
reference element is in a fixed
container, use the fixed
strategy.
Read More
modifiers
modifiers?: PopperJS$Modifiers;
An object containing custom settings for the
Popper.js modifiers.
You can use this property to override their settings or to inject your custom
ones.
Usage with ReactDOM.createPortal
Popper.js is smart enough to work even if the popper and reference
elements aren't in the same DOM context.
This means that you can use
ReactDOM.createPortal
(or any pre
React 16 alternative) to move the popper component somewhere else in the DOM.
This can be useful if you want to position a tooltip inside an
overflow: hidden
container that you want to make overflow. Please note that
you can also try the positionFixed
strategy to obtain a similar effect with
less hassle.
import { Manager, Reference, Popper } from 'react-popper';
const Example = () => (
<Manager>
<Reference>
{({ ref }) => (
<button type="button" ref={ref}>
Reference
</button>
)}
</Reference>
{ReactDOM.createPortal(
<Popper>
{({ placement, ref, style }) => (
<div ref={ref} style={style} data-placement={placement}>
Popper
</div>
)}
</Popper>,
document.querySelector('#destination')
)}
</Manager>
);
Usage without a reference HTMLElement
Whenever you need to position a popper based on some arbitrary coordinates, you
can provide Popper
with a referenceElement
property that is going to be used
in place of the referenceProps.getRef
React ref.
The referenceElement
property must be an object with an interface compatible
with an HTMLElement
as described in the
Popper.js virtualElement documentation,
this implies that you may also provide a real HTMLElement if needed.
If referenceElement
is defined, it will take precedence over any
referenceProps.ref
provided refs.
import { Popper } from 'react-popper';
class VirtualReference {
getBoundingClientRect() {
return {
top: 10,
left: 10,
bottom: 20,
right: 100,
width: 90,
height: 10,
};
}
}
const virtualReferenceElement = new VirtualReference();
const Example = () => (
<Popper referenceElement={virtualReferenceElement}>
{({ ref, style, placement, arrowProps }) => (
<div ref={ref} style={style} data-placement={placement}>
Popper element
<div ref={arrowProps.ref} style={arrowProps.style} />
</div>
)}
</Popper>
);
Flow and TypeScript types
This library is built with Flow but it supports TypeScript as well.
You can find the exported Flow types in src/index.js
, and the TypeScript
definitions in typings/react-popper.d.ts
.
Running Locally
clone repo
git clone git@github.com:FezVrasta/react-popper.git
move into folder
cd ~/react-popper
install dependencies
npm install
or yarn
run dev mode
npm run demo:dev
or yarn demo:dev
open your browser and visit:
http://localhost:1234/