@bthlabs/react-custom-popup

react-custom-popup

React Custom Popup is a React component for simply building custom popups and modals.

Installation

react-custom-popup requires React 16.4.0 or later and ReactDOM 16.4.0 or later.

yarn add --dev react-custom-popup

This assumes that you’re using yarn package manager with a module bundler like Webpack.

Usage

The following snippet shows the example usage of react-custom-popup.

import React from 'react';
import Popup from 'react-custom-popup';

class App extends React.Component {
  constructor (props) {
    super(props);

    this.refButton = React.createRef();

    this.state = {
      popupVisible: false
    };
  }
  onShowPopupButtonClick (event) {
    event.stopPropagation();
    event.preventDefault();

    this.setState({popupVisible: true});
  }
  onHidePopup (event) {
    event.stopPropagation();
    event.preventDefault();

    this.setState({popupVisible: false});
  }
  render () {
    return (
      <React.Fragment>
        <button
          ref={this.refButton}
          onClick={this.onShowPopupButtonClick}
        >
          Show Popup
        </button>

        <Popup
          anchor={this.refButton}
          visible={this.state.popupVisible}
          onOverlayClick={this.onHidePopup}
        >
          <div>
            <h2>Hello, I'm a popup!</h2>
            <p>
              <button onClick={this.onHidePopup}>Close</button>
            </p>
          </div>
        </Popup>
      </React.Fragment>
    );
  }
}

Styling

react-custom-popup includes CSS file that provides generic styles for the popup. It's recommended to include it in your project's styles.

You can customize aspects of the popup's layout by passing a custom CSS class using the className prop.

API

Popup

This is the custom popup component. It renders the popup in a React portal.

Example DOM structure rendered by the component:

<div className="bthlabs-react-custom-popup">
    <div className="bthlabs-rcp-overlay" />
    <div className="bthlabs-rcp-inner">
      <!-- Children will be rendered here -->
    </div>
</div>

The div.bthlabs-rcp-inner will be positioned according to the anchor. If anchor isn't passed, the position will default to left: 0px; top: 0px;, unless modified by onLayout prop.

Props

• anchor (React ref, optional) - a ref to an anchor element which will be used to position the inner layer.
• className (string, optional) - custom CSS class.
• hideOverlay (boolean, optional) - allows the wrapping component to hide the overlay. Defaults to false.
• visible (boolean, required) - specifies whether the popup is visible.
• onLayout (function, optional) - callback which allows the wrapping component to modify the inner layer's layout. Read below for more information.
• onOverlayClick (function, optional) - onClick handler for the div.bthlabs-rcp-overlay element.

The onLayout callback

The onLayout prop allows the wrapping component to modify the inner layer's layout. If specified, it should accept an array of integers ([<left>, <top>]) and return an array of either two or more integers ([<left>, <top>, <width>, <height>]). The width and height fields can be omitted.

Example onLayout callback:

const onLayout = (layout) => {
  return [
    layout[0] + 10, // left
    layout[1] + 20, // top
    100,            // width
    200             // height
  ];
};

This function would shift the inner layer by 10px to the right and 20px to the bottom and set its size to 100px of width and 200px of height.

Development

To bootstrap the development environment, clone the repo and run npm install from the root directory.

The package.json file provides the following scripts:

• build - builds the library modules,
• build:example - builds the example project,
• lint - performs an eslint run over the source code,
• test - performs a single test run,
• test:watch - starts karma with watcher.

NOTE: Tests require Chromium to be installed and available in the path. Consult karma-chrome-launcher docs for more info.

Contributing

If you think you found a bug or want to send a patch, feel free to contact me through e-mail.

If you're sending a patch, make sure it passes eslint checks and is tested.

Author

react-custom-popup is developed by Tomek Wójcik.

License

react-custom-popup is licensed under the MIT License.