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.
|