Managing Modal Dialogs in React: react-modal vs react-modal-hook vs react-modal-promise

Modals are a common UI pattern, but implementing them correctly in React—especially with proper focus management, accessibility, and state isolation—can be tricky. The three packages under review each solve this problem differently: one as a traditional component (react-modal), one using hooks (react-modal-hook), and one treating modals as async functions (react-modal-promise). Let’s compare how they work in practice.

🧱 Core Architecture: Component vs Hook vs Promise

react-modal is a standalone React component that renders a modal dialog when its isOpen prop is true. You control visibility via local or global state, and it handles ARIA attributes, focus trapping, and overlay clicks out of the box.

// react-modal: Controlled component
import React, { useState } from 'react';
import Modal from 'react-modal';

function App() {
  const [modalIsOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      <Modal isOpen={modalIsOpen} onRequestClose={() => setIsOpen(false)}>
        <h2>Hello</h2>
        <button onClick={() => setIsOpen(false)}>Close</button>
      </Modal>
    </div>
  );
}

react-modal-hook uses custom hooks to separate modal logic from rendering. You define a modal once and trigger it anywhere using a hook-generated function.

// react-modal-hook: Hook-based modal
import { useModal } from 'react-modal-hook';

function ConfirmModal({ onConfirm, onCancel }) {
  return (
    <div className="modal">
      <p>Are you sure?</p>
      <button onClick={onConfirm}>Yes</button>
      <button onClick={onCancel}>No</button>
    </div>
  );
}

function App() {
  const [showConfirm, hideConfirm] = useModal(() => (
    <ConfirmModal
      onConfirm={() => { console.log('Confirmed'); hideConfirm(); }}
      onCancel={hideConfirm}
    />
  ));

  return <button onClick={showConfirm}>Delete Item</button>;
}

react-modal-promise wraps modals in a Promise interface. Calling a modal function returns a Promise that resolves when the user takes action.

// react-modal-promise: Async modal
import { useModalPromise } from 'react-modal-promise';

function ConfirmDialog({ isOpen, onResolve }) {
  if (!isOpen) return null;
  return (
    <div className="modal">
      <p>Delete this item?</p>
      <button onClick={() => onResolve(true)}>Yes</button>
      <button onClick={() => onResolve(false)}>No</button>
    </div>
  );
}

function App() {
  const confirm = useModalPromise(ConfirmDialog);

  const handleDelete = async () => {
    const result = await confirm();
    if (result) {
      // Proceed with deletion
    }
  };

  return <button onClick={handleDelete}>Delete</button>;
}

⚠️ Important: As of 2024, react-modal-hook appears to be deprecated. Its GitHub repository is archived, and there have been no npm releases since 2020. New projects should avoid it unless maintaining legacy code.

🔌 Integration Requirements

Each package imposes different structural requirements on your app.

• react-modal requires you to call Modal.setAppElement() once at startup to ensure screen readers ignore background content. This is a one-time setup but easy to forget.

// Required for accessibility
import Modal from 'react-modal';
Modal.setAppElement('#root');

• react-modal-hook needs no global setup, but modals are rendered outside the triggering component’s subtree (typically appended to document.body), which can complicate styling or context access.

• react-modal-promise requires a <ModalProvider> at the root of your app to manage the modal queue:

// react-modal-promise: Provider required
import { ModalProvider } from 'react-modal-promise';

function Root() {
  return (
    <ModalProvider>
      <App />
    </ModalProvider>
  );
}

♿ Accessibility and Focus Management

react-modal has the most robust accessibility support. It automatically:

• Traps focus inside the modal
• Restores focus to the triggering element on close
• Sets aria-hidden="true" on background content
• Supports role="dialog" and aria-modal="true"

react-modal-hook does not include built-in accessibility features. You must manually implement focus trapping and ARIA attributes.

react-modal-promise also lacks native accessibility utilities. Since it’s a thin wrapper around your own modal component, accessibility depends entirely on your implementation.

🔄 State and Data Flow

• With react-modal, modal state lives in your component (or global store). Data flows in via props; actions flow out via callbacks.

• react-modal-hook encapsulates state inside the hook. You pass callbacks to the modal component to communicate back.

• react-modal-promise inverts control: instead of passing callbacks, you resolve(value) from inside the modal, and the calling code receives the value via await.

This makes react-modal-promise especially clean for simple yes/no or input dialogs:

// Example: Login modal that returns credentials
const login = useModalPromise(LoginModal);

const creds = await login();
if (creds) {
  authenticate(creds);
}

Whereas with react-modal, you’d need to lift state or use refs:

// More verbose with react-modal
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');

const handleSubmit = () => {
  authenticate({ email, password });
  setIsOpen(false);
};

🛠️ When to Use Which

💡 Final Recommendation

For new projects, your safest bet is react-modal—it’s actively maintained, battle-tested, and handles accessibility correctly by default. If your use case involves frequent modal interactions that return values (like confirmations or small forms), layer react-modal-promise on top of your own accessible modal component—but don’t rely on it for accessibility.

Avoid react-modal-hook in new code due to its unmaintained status. While its hook-based API was innovative in 2019, modern alternatives like @radix-ui/react-dialog or custom hook wrappers around react-modal offer better long-term viability.

Remember: no modal library replaces thoughtful UX. Always test with keyboard navigation and screen readers, regardless of which package you choose.