react-modal-orchestrator

A centralized and flexible modal management system for React applications, now with lazy loading!

react-modal-orchestrator provides a clean, decoupled architecture for managing modals. Instead of controlling modal state with useState in every component, you can register all your modals in one place and trigger them from anywhere in your application.

Additionally, by using React.lazy when registering your modals in your modal dictionary, modal components are only loaded when they are first opened, reducing your application's initial bundle size.

Core Concepts

• ModalOrchestrator: A provider component that wraps your application and powers the entire modal system.
• ModalHandler: A component that listens for active modals and renders them. It now includes React.Suspense to handle lazy-loaded components.
• Modal Dictionary: A simple JavaScript object where you map a unique name to each dynamically imported modal component.
• useContext for Control: Use React's useContext hook to access the openModal and closeModal functions from anywhere in your component tree.

Installation

npm install react-modal-orchestrator

Setup

First, you need to wrap your application with the ModalOrchestrator and place the ModalHandler within it.

1. Create a Lazy-Loaded Modal Dictionary

To take advantage of code-splitting, define your modal dictionary using React.lazy. This tells React to load the component code only when it's first rendered.

Create a file (e.g., modals.ts) to define and register your modals.

// components/MyFirstModal.tsx
import React, { useContext } from "react";
import {ModalDispatchContext} from "react-modal-orchestrator";

// Note: The component must be a default export for React.lazy to work
export const MyFirstModal = ({ title }) => {
  const { closeModal } = useContext(ModalContext);
  return (
    <div>
      <h2>{title}</h2>
      <p>This is my first modal!</p>
      <button onClick={closeModal}>Close</button>
    </div>
  );
};
export default MyFirstModal;


// modals.ts
import React from "react";

export const modalDictionary = {
  MY_FIRST_MODAL: React.lazy(() => import("./components/MyFirstModal")),
  // ... register other lazy-loaded modals here
};

2. Wrap Your App

In your main application file (e.g., App.tsx), import the ModalOrchestrator, ModalHandler, and your modal dictionary.

// App.tsx
import { ModalOrchestrator, ModalHandler } from "react-modal-orchestrator";
import { modalDictionary } from "./modals";

function App() {
  return (
    <ModalOrchestrator modals={modalDictionary}>
      {/* Your application components */}
      <h1>My App</h1>
      <TriggerButton />

      {/* 
        Place the handler at the top level.
        You can customize the loading fallback in your own Suspense boundary.
      */}
      <ModalHandler />
    </ModalOrchestrator>
  );
}

Usage

Opening a Modal

No more passing state around to conditionally render modals.

If your modal manages its open state, simply set its isOpen to true.

To open a modal, import ModalDispatchContext, get the openModal function from the context, and call it with the registered name of the modal you want to open.

If your modal needs props, just pass an object of props as the 2nd argument to openModal.

// components/TriggerButton.tsx
import React, { useContext } from "react";
import {ModalDispatchContext} from "react-modal-orchestrator";

const TriggerButton = () => {
  const { openModal } = useContext(ModalContext);

  const handleClick = () => {
    // Open the modal and pass props to it
    openModal("MY_FIRST_MODAL", { title: "Hello World!" });
  };

  return <button onClick={handleClick}>Open Modal</button>;
};

Closing a Modal

The ModalDispatchContext also provides a closeModal function to your modal component via context. Use the useContext hook to access it.

// components/MyFirstModal.tsx
import React, { useContext } from "react";
import {ModalDispatchContext} from "react-modal-orchestrator";

// Ensure the component is a default export
const MyFirstModal = ({ title }) => {
  const { closeModal } = useContext(ModalContext); // Get closeModal from context

  return (
    <div>
      <h2>{title}</h2>
      <button onClick={closeModal}>Close Me</button>
    </div>
  );
};

export default MyFirstModal;

License

This project is licensed under the ISC License.