React Overlay Manager

react-overlay-manager is a flexible and lightweight solution for managing modals, drawers, and other overlay components in React applications. It is built on top of Ant Design but can be easily extended to support other overlay types.

Key Features

• Centralized Overlay Management:
  Manage all overlays in a single place. No need to handle state or visibility of each overlay individually in your components.

• UI Library Agnostic:
  The overlay system works independently of the UI library used in your project. While this readme uses Ant Design (with Modal and Drawer), you can easily integrate it with Material UI, Tailwind, or any other UI framework.

• Minimal Re-Renders & Side Effects:
  By reducing unnecessary re-renders, the package ensures high performance, even with multiple overlays. Side effects are contained within the overlays, preventing them from affecting other parts of the application.

• Simple API:
  Use the useOverlay hook to open or close overlays easily, while customizing their behavior with simple configuration options.

• Scalable & Customizable:
  Add, update, or remove overlays with minimal effort. Each overlay is highly configurable, and the solution scales effortlessly with your application's needs.

• Error Handling:
  Robust error handling ensures the system doesn’t break if an overlay handler is missing or an error occurs, making it more reliable for production environments.

Installation

Install the package using npm or yarn:

npm install react-overlay-manager

Setup

Wrap your application in the OverlayProvider and define the overlays you want to use. Each overlay is defined with a unique overlayName and a corresponding React component.

import { Drawer, Modal } from 'antd';
import { OverlayProvider } from 'react-overlay-manager';

const App = () => {
  return (
    <OverlayProvider
      overlays={[
        {
          overlayName: 'modal',
          Overlay: ({ open, Element, config }) => (
            <Modal open={open} {...config}>
              <Element />
            </Modal>
          ),
        },
        {
          overlayName: 'drawer',
          Overlay: ({ open, Element, config }) => (
            <Drawer open={open} {...config}>
              <Element />
            </Drawer>
          ),
        },
      ]}
    >
      {/* UI */}
    </OverlayProvider>
  );
};

Usage

Use the useOverlay hook to control overlays dynamically. The open function allows you to open a specific overlay with a custom element and configuration, while the close function closes it.

import { DrawerProps, ModalProps } from 'antd';
import { OverlayProvider } from 'react-overlay-manager';

const SomeElement = ({ fname }: { fname: string }) => {
  return <div>Hello, {fname}!</div>;
};


const HomePage = () => {
  const { open, close } = useOverlay();

  return (
    <div>

      <button
        onClick={() => {
          open<ModalProps>('modal', <SomeElement fname="John" />, {
            closable: true,
            onCancel: () => close('modal'),
            width: 700,
          });
        }}
      >
        Open Large Modal
      </button>

      <button
        onClick={() => {
          open<ModalProps>('modal', <SomeElement fname="John" />, {
            closable: true,
            onCancel: () => close('modal'),
            width: 400,
          });
        }}
      >
        Open Small Modal
      </button>

      <button
        onClick={() => {
          open<DrawerProps>('drawer', <SomeElement fname="John" />, {
            closable: true,
            width: 300,
          });
        }}
      >
        Open Drawer
      </button>

    </div>
  );
};

In this example, I have used Ant Design to demonstrate how to implement overlays such as modals and drawers. However, the solution is highly flexible and can be extended to support other UI libraries, such as Material UI or any other UI library of your choice. You can easily swap the components (e.g., Modal or Drawer) with equivalent ones from your preferred UI library by updating the Overlay components within the OverlayProvider. The core logic remains the same, allowing you to seamlessly integrate with different UI frameworks while keeping the overlay management centralized.