Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alex-cory/use-react-modal
🖼 React hook for Modals
https://github.com/alex-cory/use-react-modal
hook lightbox modal portal react react-modal use-dialog use-lightbox use-modal usedialog usemodal
Last synced: about 1 month ago
JSON representation
🖼 React hook for Modals
- Host: GitHub
- URL: https://github.com/alex-cory/use-react-modal
- Owner: alex-cory
- License: mit
- Created: 2019-10-26T08:58:14.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T11:05:37.000Z (almost 2 years ago)
- Last Synced: 2024-10-28T17:39:28.937Z (about 2 months ago)
- Topics: hook, lightbox, modal, portal, react, react-modal, use-dialog, use-lightbox, use-modal, usedialog, usemodal
- Language: TypeScript
- Homepage:
- Size: 2.56 MB
- Stars: 80
- Watchers: 4
- Forks: 4
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: license.md
Awesome Lists containing this project
- fucking-awesome-react-hooks - `use-react-modal`
- awesome-react-hooks-cn - `use-react-modal`
- awesome-react-hooks - `use-react-modal`
- awesome-react-hooks - `use-react-modal`
README
useModal
🖼 React hook for Modals
Simple, lightweight hook for Modals/Dialogs.
This hook is also isomorphic, meaning it works with SSR (server side rendering).
Features
--------
- SSR (server side rendering) support
- TypeScript support
- 2 dependencies ([use-ssr](https://github.com/alex-cory/use-ssr), [react-useportal](https://github.com/alex-cory/react-useportal))
- Built in state
### Examples
- [Example](https://codesandbox.io/s/usemodal-dj3du)
Installation
------------
```shell
yarn add use-react-modal or npm i -S use-react-modal
```
Usage
-----
### Basic Usage
```jsx
import useModal from 'use-react-modal'
const App = () => {
const { isOpen, openModal, closeModal, Modal } = useModal()
return (
<>
Open Me!
{isOpen && (
close
Whatever you put here will be centered to the middle of the screen.
)
>
)
}
```
### With Provider
```jsx
import useModal, { Provider } from 'use-react-modal'
const MyComponent = () => {
const { isOpen, openModal, Modal } = useModal()
return (
<>
Open Me!
{isOpen && (
Now, whatever you put here will be centered AND have a backdrop
with the color specified in the Provider
)
>
)
}
const App = () => (
)
```
**Make sure you are passing the html synthetic event to the `openModal` and `toggleModal` . i.e. `onClick={e => openModal(e)}`**
### Usage with a `ref`
If for some reason, you don't want to pass around the `event` to `openModal` or `toggleModal`, you can use a `targetRef` like this.
```jsx
import useModal from 'use-react-modal'
const App = () => {
const { targetRef, openModal, closeModal, isOpen, Modal } = useModal()
return (
<>
{/* see below how I don't have to pass the event if I use the ref */}
openModal()}>
Open Modal
{isOpen && (
Close me!, hit ESC or
Cool Modal 😜
)}
>
)
}
```
Options
-----
| Option | Description |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `background` | sets the color of the backdrop, if nothing is set, there will be no backdrop |
| `closeOnOutsideClick` | This will close the modal when not clicking within the modal. Default is `true` |
| `closeOnEsc` | This will allow you to hit ESC and it will close the modal. Default is `true` |
| `bindTo` | This is the DOM node you want to attach the modal to. By default it attaches to `document.body` |
| `isOpen` | This will be the default for the modal being open or closed. Default is `false` |
| `onOpen` | This is used to call something when the modal is opened |
| `onClose` | This is used to call something when the modal is closed |
| html event handlers (i.e. `onClick`) | These can be used instead of `onOpen`. |
### Option Usage
```js
const {
openModal,
closeModal,
toggleModal,
isOpen,
Modal,
// if you don't pass an event to openModal, closeModal, or toggleModal, you will need to
// put this on the element you want to interact with/click to open the modal
targetRef,
// this allows you to interact directly with the backdrop/overlay
backdropRef,
// this allows you to interact directly with the modal
modalRef,
} = useModal({
// sets the color of the backdrop, if nothing is set, the backdrop will be transparent unless it's set in the Provider
// setting to `null` removes any background set in the `Provider`
background: 'rgba(0, 0, 0, 0.5)',
closeOnOutsideClick: true,
closeOnEsc: true,
bindTo, // attach the portal to this node in the DOM
isOpen: false,
// `event` has all the fields that a normal `event` would have such as `event.target.value`, etc.
// with the additional `portal` and `targetEl` added to it as seen in the examples below
onOpen: (event) => {
// can access: event.portal, event.targetEl, event.event, event.target, etc.
},
// `onClose` will not have an `event` unless you pass an `event` to `closePortal`
onClose({ targetEl, event, portal }) {},
// `targetEl` is the element that you either are attaching a `ref` to
// or that you are putting `openPortal` or `togglePortal` or `closePortal` on
// in addition, any event handler such as onClick, onMouseOver, etc will be handled the same
onClick({ targetEl, event, portal }) {}
})
```
Can also do array destructuring
```js
const [openModal, closeModal, isOpen, Modal, toggleModal, targetRef, portalRef, modalRef] = useModal()
```
Todos
------
- [ ] animations 😜
- [ ] React Native support. [1](https://github.com/zenyr/react-native-portal) [2](https://github.com/cloudflare/react-gateway) [3](https://medium.com/@naorzruk/portals-in-react-native-22797ba8aa1b) [4](https://stackoverflow.com/questions/46505378/can-we-have-react-16-portal-functionality-react-native) [5](https://github.com/callstack/react-native-paper/blob/master/src/components/Portal/PortalManager.tsx) Probably going to have to add a `Provider`...
- [ ] add correct return types
- [ ] tests (priority)
- [ ] potential syntax ideas
```
// then you can change the order of the array destructuring syntax
// CustomModal, CustomCloseButton
const { Modal, CloseButton } = useProvider()
// customize the modal animations
const { Modal } = useModal({
onOpen({ modal }) {
modal.current.style.cssText = `
/* do some animation in */
`
},
onClose({ modal }) {
modal.current.style.cssText = `
/* do some animation out */
`
}
})
// customize the modal animations idea 2
const { Modal } = useModal({
animateIn: `
/* css for animating in */
`,
animateOut: `
/* css for animating out */
`,
})
// customize the modal animations idea 3
// maybe have some predefined options?
const { Modal } = useModal({
animate: 'fade-in-out', // 'slide-in-top', etc...
})
// check out http://reactcommunity.org/react-modal/styles/transitions.html
```