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