https://github.com/remoteoss/react-url-modal
A React library to help you keep track of your modal state using the URL
https://github.com/remoteoss/react-url-modal
react
Last synced: 9 months ago
JSON representation
A React library to help you keep track of your modal state using the URL
- Host: GitHub
- URL: https://github.com/remoteoss/react-url-modal
- Owner: remoteoss
- License: mit
- Created: 2022-01-27T15:24:17.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-09-23T16:14:36.000Z (almost 3 years ago)
- Last Synced: 2025-09-10T12:02:25.480Z (10 months ago)
- Topics: react
- Language: TypeScript
- Homepage: http://react-url-modal.vercel.app
- Size: 903 KB
- Stars: 128
- Watchers: 3
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React URL Modal
A React library to help you keep track of your modal state using the URL.
## Features
- ☁️ Have URL's for modals
- 🔒 Encode all the parameters sent to a modal
- 🦄 Works on any framework since it uses [the history api](https://developer.mozilla.org/en-US/docs/Web/API/History_API)
- 📦 Headless and tiny
- 🚀 Supports React Portals
## Documentation
[Documentation](https://react-url-modal.vercel.app)
To create a new instance of modals, import the `URLModal` and pass the modals you have in your application:
```jsx
import { URLModal } from 'react-url-modal';
import { CreateAccount, EditAccount } from './Modals';
export const App = () => (
);
```
To open this modal from any button in your application, use the `openModal` function and pass the name of the modals and any params this modal needs:
```jsx
import { openModal } from 'react-url-modal';
openModal({
name: 'editAccount',
params: {
userId: user.id,
},
})
}
>
Edit your profile
;
```
If you want to use a link to open the modals that's also possible taking advantage of the `encodeUrlParams` and creating a link:
```
Edit account
```
Then, in your modal you will have access to any param you passed to it:
```jsx
const ModalWithParams = ({
params,
onClose,
}: {
params: { [key: string]: string },
onClose: () => void,
}) => (
<>
{params.userId}
CloseModal
>
);
```
You can also pass a `Wrapper` to the `` component which will wrap all your modals and will have access to the `onClose` function:
```jsx
(
<>
{children}
x
>
)}
/>
```
To see all the available props, please check the API reference below.
## API Reference
#### URLModal
```jsx
```
| Parameter | Type | Description |
| :-------------- | :------------------------------------------------------ | :-------------------------------------------------------------- |
| `modals` | `[name: string]: React Component or Promise` | **Required** |
| `Wrapper` | `React Component` | A component to wrap each modal with |
| `usePortal` | `boolean` | Should this modal be mounted on a portal |
| `portalElement` | `HTML Element` | A component to mount the modals in, defaults to body |
| `adapter` | `null or "nextjs"` | If set to NextJS it will use next router instead of history API |
#### openModal
Will open any modal you declared in `modals` by passing its name.
```js
openModal({
name: 'createAccountForm'
params: {
hello: 'world'
}
})
```
| Parameter | Type | Description |
| :-------- | :------------------------ | :-------------------------------------- |
| `name` | `string` | **Required**. Name of the modal to open |
| `params` | `{[key: string]: string}` | Any params this modal need |
#### closeModal
Close all open modals.
```js
closeModal();
```
#### isModalOpen
Checks if a modal passed is open at the moment the function is called
```js
isModalOpen('createAccountForm');
```
| Parameter | Type | Description |
| :-------- | :------- | :-------------------------------------------- |
| `name` | `string` | **Required**. Name of the modal to check open |
#### encodeUrlParams
Useful if you want to open a modal by a link instead of a button. It will create the url from the params passed.
```js
router.push({
pathname: '/account',
query: {
modal: 'editAccount',
params: encodeUrlParams({
id: user.id,
}),
},
});
```
| Parameter | Type | Description |
| :-------- | :------- | :-------------------------------------- |
| `params` | `Object` | **Required**. Object you want to encode |
## Run Locally
Clone the project
```bash
git clone git@github.com:remoteoss/react-url-modal.git
```
Go to the project directory
```bash
cd react-url-modal
```
Install dependencies
```bash
yarn && yarn add next --peer
```
Start the server
```bash
yarn dev
```
To open the example and test your changes please in another tab and run:
```bash
cd example
yarn && yarn dev
```
## Running Tests
To run tests, run the following command
```bash
yarn test
```
To run coverage you can run:
```bash
yarn test:coverage
```
## License
[MIT](https://choosealicense.com/licenses/mit/)