Package Exports
- react-useportal
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-useportal) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
usePortal
🌀 React hook for using Portals
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).
This hook is also isomorphic, meaning it works with SSR (server side rendering).
Features
- SSR (server side rendering) support
- TypeScript support
- 1 dependency (use-ssr)
- Built in state
Examples
- Modal Example - Next.js - codesandbox container (sometimes buggy, if so try this example)
- Modal Example - create-react-app
Installation
yarn add react-useportal or npm i -S react-useportalUsage
Stateless
import usePortal from 'react-useportal'
<Portal>
This text is portaled at the end of document.body!
</Portal>
<Portal bindTo={document && document.getElementById('san-francisco')}>
This text is portaled into San Francisco!
</Portal>With State
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 (
<>
<button onClick={openPortal}>
Open Portal
</button>
{isOpen && (
<Portal>
<p>
This Portal handles its own state.{' '}
<button onClick={closePortal}>Close me!</button>, hit ESC or
click outside of me.
</p>
</Portal>
)}
</>
)
}Need Animations?
import usePortal from 'react-useportal'
const App = () => {
const { openPortal, closePortal, isOpen, Portal } = usePortal()
return (
<>
<button onClick={openPortal}>
Open Portal
</button>
<Portal>
<p className={isOpen ? 'animateIn' : 'animateOut'}>
This Portal handles its own state.{' '}
<button onClick={closePortal}>Close me!</button>, hit ESC or
click outside of me.
</p>
</Portal>
</>
)
}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
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 resource 2. Maybe something like
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')- tests (priority)
- make work without requiring the html synthetic event
- add example for tooltip (like this one)
- add as many examples as possible 😊
- fix code so maintainability is A
- optimize badges see awesome badge list
- document when you are required to have synthetic event
- make isomorphic
- continuous integration
- greenkeeper