overlay-kit

Traditional overlay management is often imperative, requiring developers to manually manage visibility state (e.g., using useState) and handle open/close event logic within the parent component. This leads to complex state management, repetitive event handling, and tightly coupled UI/logic.

overlay-kit uses a Declarative Overlay Pattern where overlays are managed based on behavior rather than explicit state. Instead of managing an isOpen boolean, you call overlay.open(), which provides the necessary control functions (isOpen, close) directly to the overlay component's render function. This improves readability, reduces code duplication, and promotes co-location of logic.

// Declarative Approach with overlay-kit
import { overlay } from 'overlay-kit';

function Overlay() {
  return (
    <Button
      onClick={() => {
        overlay.open(({ isOpen, close }) => (
          <Dialog open={isOpen} onClose={close}>
            <DialogTitle>Declarative Overlay</DialogTitle>
            <DialogActions>
              <Button onClick={close}>OK</Button>
              <Button onClick={close}>Cancel</Button>
            </DialogActions>
          </Dialog>
        ));
      }}
    >
      Open
    </Button>
  );
}

The choice between these two methods depends on whether you need to await a result from the overlay:

• overlay.open: Used for basic overlay operations where you don't need to capture a return value from the overlay's lifecycle.
• overlay.openAsync: Returns a Promise that resolves when the overlay is closed via the close function. This is ideal for workflows like confirmation dialogs where the calling code needs to know the user's choice.

overlay.openAsync supports TypeScript generics to define the type of the resolved value.

// overlay.open
overlay.open(({ isOpen, close }) => (
  <Dialog open={isOpen} onClose={close}>
    <p>Simple overlay</p>
  </Dialog>
));

// overlay.openAsync
const result = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <Dialog open={isOpen} onClose={() => close(false)}>
    <Button onClick={() => close(true)}>Confirm</Button>
  </Dialog>
));

console.log(result ? 'Yes' : 'No');

When using MUI's Dialog component, map the open prop to isOpen and the onClose prop to the close function provided by the overlay.open callback. This allows overlay-kit to manage the visibility and dismissal of the MUI dialog.

import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';

function App() {
  return (
    <Button
      variant="contained"
      onClick={() => {
        overlay.open(({ isOpen, close }) => (
          <Dialog open={isOpen} onClose={close}>
            <DialogTitle>Are you sure you want to continue?</DialogTitle>
            <DialogActions>
              <Button onClick={close}>No</Button>
              <Button onClick={close}>Yes</Button>
            </DialogActions>
          </Dialog>
        ));
      }}
    >
      Open Confirm Dialog
    </Button>
  );
}

When using Chakra v3's Dialog.Root, you must sync its open state with the isOpen state provided by overlay-kit.

To handle automatic dismissal (like backdrop clicks or the ESC key), use the onOpenChange prop. Since onOpenChange receives an object { open: boolean }, you should call close() whenever !e.open is true.

Ensure your application is wrapped in both ChakraProvider (with a value={defaultSystem}) and OverlayProvider.

import { OverlayProvider, overlay } from 'overlay-kit';
import { Button, ChakraProvider, Dialog, Portal, defaultSystem } from '@chakra-ui/react';

function App() {
  return (
    <Button
      colorPalette="blue"
      onClick={() => {
        overlay.open(({ isOpen, close }) => (
          <Dialog.Root open={isOpen} onOpenChange={(e) => !e.open && close()}>
            <Portal>
              <Dialog.Backdrop />
              <Dialog.Positioner>
                <Dialog.Content>
                  <Dialog.Header>
                    <Dialog.Title>Are you sure you want to continue?</Dialog.Title>
                  </Dialog.Header>
                  <Dialog.Footer gap={2}>
                    <Button variant="outline" onClick={close}>
                      No
                    </Button>
                    <Button colorPalette="blue" onClick={close}>
                      Yes
                    </Button>
                  </Dialog.Footer>
                </Dialog.Content>
              </Dialog.Positioner>
            </Portal>
          </Dialog.Root>
        ));
      }}
    >
      Open Confirm Dialog
    </Button>
  );
}