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

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 git@github.com: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