# React Awesome Popups
> A lightweight, extendable, fast performing, highly customizeable, production ready React Component that renders an animated set of popups.
[See this project at NPM](https://www.npmjs.com/package/react-awesome-popups)
[
](https://github.com/JSANJ/react-awesome-popups/blob/master/demo/public/demo.gif)
## Key Features
- 60 FPS animated popups
- Customizable animated transitions
- Customizable colours
- OnPress ripple effect
- Look and feel customisable and extendable in two ways: via custom **CSS stylesheet** override or **style** prop which can be determined at runtime.
## Live demo
Checkout the live demo at my **web portfolio** page.
You can run this demo locally on `3000` by:
1. Cloning this repository
`git clone https://github.com/JSANJ/react-awesome-popups.git`
2. Navigate to the demo directory
`cd react-awesome-popups && cd demo`
2. Installing the dependencies **in the demo directory**
`npm install --dev`
3. Starting the demo
`npm start`
## Installation
```
npm install --save react-awesome-poups
```
###`AwesomePopupsContainer`
#### `AwesomePopupsContainer` API
**AwesomePopupsContainer.popup(component, animStates)**
Adds the popup component and starts the animation using the animStates **start** key.
- component: (AwesomePopup) - popup component to be displayed
- animStates: ({string: AnimState} object) - **start** and **end** keys are required.
**returns**: popupId (string)
**AwesomePopupsContainer.close(popupId)**
Performs the close animation on the popup and removes it elegantly.
- popupId: (string) - the ID of the popup acquired when added to the container.
**AwesomePopupsContainer.remove(popupId)**
Removes the popup with the given popupId immediately.
- popupId: (string) - the ID of the popup acquired when added to the container.
**AwesomePopupsContainer.remove(popupId)**
Removes the popup with the given popupId immediately.
- popupId: (string) - the ID of the popup acquired when added to the container.
#### AnimState
| Attribute | Type | Default | Description |
| :-------- | :--------: | :-------: | :------------------------------------------------------------------------------------------------------- |
| style | `string` | `null` | Render this style object as the next transitioned animation |
| duration | `number` | `0` | Sets the transition to last this long, also triggers the next state at the end |
| nextStateKey | `string` | `null` | The key of the next 'AnimState' in the 'AnimStates' object |
| unmountOnComplete | `bool` | `false` | Should unmount the component when the animation duration passes |
#### `AwesomePopupsContainer` props
| Attribute | Type | Default | Description |
| :-------- | :--------: | :-------: | :------------------------------------------------------------------------------------------------------- |
| children | `any` | `null` | The component's children to be rendered |
### `AwesomePopup`
#### `AwesomePopup` API (Internal)
**AwesomePopup.queueState(newState)**
Updates the animation state and queues the next state.
- newState: (AnimState) - an object containing the style, duration, and other animation parameters
**AwesomePopup.startUnmount()**
Begins the unmounting of the component by starting the **end** animation state.
**AwesomePopup.queueDelete(ms, popupId)**
Queues the unmounting of the component after a given delay in milliseconds.
- ms: (number) - delay in milliseconds
- popupId: (string) - ID of the popup to be sent to the container for unmounting
**AwesomePopup.doDelete(popupId)**
Calls the onUnmount function of the popup. Also triggers the onEndComplete callback
- popupId: (string) - ID of the popup to be sent to the container for unmounting
#### `AwesomePopup` props
| Attribute | Type | Default | Description |
| :-------- | :--------: | :-------: | :------------------------------------------------------------------------------------------------------- |
| onClick | `function` | `null` | Triggered when the component is clicked |
| onStart | `function` | `null` | Triggered when the component is mounted |
| onStartComplete | `function` | `null` | Triggered when the component reaches its 'wait' animation |
| onEnd | `function` | `null` | Triggered when the component is beginning its removal |
| onEndComplete | `function` | `null` | Triggered when the component is just about to be unmounted |
| popupId | `string` |`generated`| This is a key added to the popup when inserted into the AwesomePopupsContainer |
| closeButton | `component`| `auto` | An object placed at the end of the container to trigger closing the popup when pressed |
| style | `object` | `null` | An object to add as the React css style of the component |
| type | `string` | `custom` | ( success | warning | error | info | neutral ) Substring of the css style to be applied to the component |
| animStates | `object` | `null` | {string:AnimState} key-value object for animating the component |
| children | `any` | `null` | The component's children to be rendered |
### `AwesomePopupStates`
This is a {string:AnimStates} key-value object. Each 'AnimStates' is then a {string:AnimState} object
**clip**: An AnimStates object for a default clipping animation
**fade**: An AnimStates object for a default fade animation
### `ReactAwesomePopups` basic example
Checkout this example live on the [storyboard](https://justinsj.com/demo/react-awesome-popups/storybook/).
**In the App.js File**
```
import { AwesomePopupsContainer } from 'react-awesome-popups'
global.ReactAwesomePopups = new React.createRef();
function App(props) {
return (
);
}
export default App;
```
**Then in any other file, call the API**
```
import { AwesomePopup } from 'react-awesome-popups'
global.ReactAwesomePopups.popup(
Hello there!
);
```
**You can create a custom popup to override the AwesomePopup class**
```
import { AwesomePopup } from 'react-awesome-popups'
class YourAwesomePopup extends AwesomePopup {
startUnmount() {
// New start unmount logic
}
}
```
## Developer Installation
Establish git hooks link
Navigate to **project directory** and run:
```
git config --local core.hooksPath git_hooks
```
### Future Work
## React Native Version
(In Progress)
## Author
#### Justin San Juan
- Checkout my Full-Stack Web Developer Website
- Other open source projects @ Code Laboratory
- A scope of my work @ Web Developer Portfolio
## License
MIT. Copyright (c) 2020 Justin San Juan.