Need to make dropdowns, lightboxes/modals/dialogs, global message notifications, or tooltips in React? React Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component ([react docs](https://reactjs.org/docs/portals.html)).
### Examples
- Code Sandbox Example
Installation
------------
```shell
yarn add react react-dom react-useportal
```
Usage
-----
### Stateless
```jsx
import usePortal from 'react-useportal'
This text is portaled at the end of document.body!
This text is portaled into San Francisco!
```
### With State
```jsx
import usePortal from 'react-useportal'
const App = () => {
var { openPortal, closePortal, isOpen, Portal } = usePortal()
// want to use array destructuring? You can do that too
var [openPortal, closePortal, isOpen, Portal] = usePortal()
return (
<>
{isOpen && (
This Portal handles its own state.{' '}
, hit ESC or
click outside of me.
This Portal handles its own state.{' '}
, hit ESC or
click outside of me.
)
}
```
**Make sure you are passing the html synthetic event to the `openPortal`. i.e. `onClick={e => openPortal(e)}`**
Options
-----
| Option | Description |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `closeOnOutsideClick` | This will close the portal when not clicking within the portal. Default is `true` |
| `closeOnEsc` | This will allow you to hit ESC and it will close the modal. Default is `true` |
| `renderBelowClickedElement` | This will put the portal right under the element that you click on. Great for dropdowns. Required to pass event to openPortal `onClick={event => openPortal(event)}` |
| `bindTo` | This is the DOM node you want to attach the portal to. By default it attaches to `document.body` |
| `isOpen` | This will be the default for the portal. Default is `false` |
### Option Usage
```js
const {
openPortal,
closePortal,
togglePortal,
isOpen,
Portal
} = usePortal({
closeOnOutsideClick: true,
closeOnEsc: true,
renderBelowClickedElement, // appear directly under the clicked element/node in the DOM
bindTo, // attach the portal to this node in the DOM
isOpen: false,
})
```
Todos
------
- [ ] add support for popup windows [resource 1](https://javascript.info/popup-windows) [resource 2](https://hackernoon.com/using-a-react-16-portal-to-do-something-cool-2a2d627b0202). Maybe something like
```jsx
const { openPortal, closePortal, isOpen, Portal } = usePortal({
popup: ['', '', 'width=600,height=400,left=200,top=200']
})
// window.open('', '', 'width=600,height=400,left=200,top=200')
```
- [ ] make isomorphic
- [ ] make work without requiring the html synthetic event & document when you are required to have it and when you are not
- [ ] clean up code
- [ ] make work with both `[openPortal, closePortal, ..., Portal] = usePortal()` and like current object destructuring
