README.md

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
• 📦 Headless and tiny
• 🚀 Supports React Portals

Documentation

Documentation

To create a new instance of modals, import the URLModal and pass the modals you have in your application:

import { URLModal } from 'react-url-modal';
import { CreateAccount, EditAccount } from './Modals';

export const App = () => (
  <URLModal
    modals={{
      createAccount: CreateAccount,
      editAccount: EditAccount,
    }}
  />
);

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:

import { openModal } from 'react-url-modal';

<button
  onClick={() =>
    openModal({
      name: 'editAccount',
      params: {
        userId: user.id,
      },
    })
  }
>
  Edit your profile
</button>;

If you want to use a link to open the modals that's also possible taking advantage of the encodeUrlParams and creating a link:

<a href=`/account?modal=editAccount&params=${encodeUrlParams({ id: user.id })}`>Edit account</a>

Then, in your modal you will have access to any param you passed to it:

const ModalWithParams = ({
  params,
  onClose,
}: {
  params: { [key: string]: string },
  onClose: () => void,
}) => (
  <>
    {params.userId}
    <button onClick={onClose}>CloseModal</button>
  </>
);

You can also pass a Wrapper to the <URLModal> component which will wrap all your modals and will have access to the onClose function:

<URLModal
  modals={{
    customWrapper: CustomWrapperModal,
  }}
  Wrapper={({ onClose, children }) => (
    <>
      {children}
      <button onClick={onClose} type="button" aria-label="Close modal">
        x
      </button>
    </>
  )}
/>

To see all the available props, please check the API reference below.

API Reference

URLModal

<URLModal
  modals={{
    test: TestModal,
  }}
/>

Parameter	Type	Description
modals	[name: string]: React Component or Promise<Component>	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.

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.

closeModal();

isModalOpen

Checks if a modal passed is open at the moment the function is called

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.

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

  git clone [email protected]:remoteoss/react-url-modal.git

Go to the project directory

  cd react-url-modal

Install dependencies

  yarn && yarn add next --peer

Start the server

  yarn dev

To open the example and test your changes please in another tab and run:

cd example
yarn && yarn dev

Running Tests

To run tests, run the following command

  yarn test

To run coverage you can run:

  yarn test:coverage

License

MIT