/react-url-modal

A React library to help you keep track of your modal state using the URL

Primary LanguageTypeScriptMIT LicenseMIT

React URL Modal

A React library to help you keep track of your modal state using the URL.

Build Passing

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 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