@qnit/react-modal-manager

A simple tool for organized modals in your application.

Usage:

1. Import the proivider component

import { ModalProvider } from 'react-modal-provider';

2. Wrap your App in ModalProvider:

<ModalProvider>
  <App />
</ModalProvider>

3. Import useModalQueue hook in the component where you whant your modal to be:

import { useModalQueue } from '@qnit/react-modal-manager';

const { modals, queueModal } = useModalQueue()

4. Use queueModal function to add a modal to a tree with either string for default modal, or react node:

const showModal = () => {
  queueModal({content: 'My Modal!'})
}

const showModal2 = () => {
  const newModal = (
    <div>
      <h1>New Modal</h1>
      <p>This is a new modal window.</p>
    </div>
  )
  queueModal({ content: newModal, onClose: () => { console.log('Modal closed'); } });
}

5. You can pass an onClose callback to the queueModal function, callback will execute before closing the modal. Async callbacks are supported and closing resolves after the callback.

Debugging with provider options

1. Universal Logs. false by default. Pass as true to see logs, warning and errors from undergoing processes and more info about your modals.

<ModalProvider options={{ universalLogs: true }}>

2. RethrowOnCloseError. true by default. Pass as false to execute closing logic despite the errors in your onClose callback.

<ModalProvider options={{ universalLogs: true, rethrowOnCloseError: false }}>

Customization

Excluding custom modals, you can customise styles of the modal differently:

Options object

You can pass options object right into queueModal function like so:

  queueModal({content: 'hihihi', onClose: () => { console.log('Modal closed') }, options: { position: 'top-right' } });

Inline styles

Just pass the styles into ModalProvider component, and they will be applied to the default modal component:

<ModalProvider styles={{ background: 'red'}}>
  <App />
</ModalProvider>

Custom default component

You can also create a component for provider to use by default using ModalOverride prop like so:

<ModalProvider ModalOverride={DefaultOverrideExample}>
  <App />
</ModalProvider>

Inside your component, import ModalGeneric type

import type { ModalGeneric } from "react-modal-provider";

And set props for your component as:

const DefaultOverrideExample: React.FC<PropsWithChildren<{} & ModalGeneric>> = ({ children, onClose, styles })

children prop will be used as a slot for content you pass to the modal and onClose will execute closing and additional callback, if you added them from queueModal

Every modal will automatically open on top of the old one and close when you press on the background.

License

MIT © 2025 Pavlo Zabuha