npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2019 – Ryan Hefner

react-popper

v1.3.6

Published

React wrapper around Popper.js

Downloads

7,613,084

Readme

React Popper

Build Status npm version npm downloads Dependency Status code style: prettier Get support or discuss

React wrapper around Popper.js.

important note: popper.js 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 --save
# or
yarn add react-popper

Via script tag (UMD library exposed as ReactPopper):

<script src="https://unpkg.com/react-popper/dist/index.umd.js"></script>

Usage

Using [email protected]? You can find its documentation clicking here

Example:

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>
);

react-popper makes use of a React pattern called "render prop", if you are not familiar with it, please read more on the official React documentation.

Using React <=15 or Preact? The components created with them don't support to return fragments, this means that you will need to wrap <Reference /> and <Popper /> into a single, common, <div /> to make react-popper work.

API documentation

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, eventsEnabled and positionFixed.

<Popper
  innerRef={(node) => this.popperNode = node}
  placement="right"
  modifiers={{ preventOverflow: { enabled: false } }}
  eventsEnabled={true}
  positionFixed={false}
>
    { props => [...] }
</Popper>
children
children: ({|
  ref: (?HTMLElement) => void,
  style: { [string]: string | number },
  placement: ?Placement,
  outOfBoundaries: ?boolean,
  scheduleUpdate: () => 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.
  • outOfBoundaries: a boolean signifying if the popper element is overflowing its boundaries.
  • scheduleUpdate: a function you can call to schedule a Popper.js position update. It will directly call the Popper#scheduleUpdate 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.

outOfBoundaries: ?boolean;

A boolean that can be used to hide the popper element in case it's overflowing from its boundaries. Read more.

eventsEnabled
eventsEnabled?: boolean;

Tells react-popper to enable or disable the Popper.js event listeners. true by default.

positionFixed

Set this property to true to tell Popper.js to use the position: fixed strategy to position the popper element. By default it's false, meaning that it will use the position: absolute strategy.

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 referenceObject 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,
    };
  }

  get clientWidth() {
    return this.getBoundingClientRect().width;
  }

  get clientHeight() {
    return this.getBoundingClientRect().height;
  }
}

// This is going to create a virtual reference element
// positioned 10px from top and left of the document
// 90px wide and 10px high
const virtualReferenceElement = new VirtualReference();

// This popper will be positioned relatively to the
// virtual reference element defined above
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 [email protected]: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/