175 lines
4.5 KiB
Markdown
175 lines
4.5 KiB
Markdown
# 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](https://yarnpkg.com/en/) package manager
|
||
with a module bundler like [Webpack](https://webpack.js.org/).
|
||
|
||
## 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](https://github.com/karma-runner/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](https://www.bthlabs.pl/).
|
||
|
||
## License
|
||
|
||
react-custom-popup is licensed under the MIT License.
|