# overlay-kit > overlay-kit is a React library for declaratively managing overlays — modals, popups, dialogs, alerts, toasts — built by Toss. It exposes a minimal imperative API (`overlay.open`, `overlay.openAsync`) that returns Promises, removes `useState` / `onClose` boilerplate, and works with any React-based UI library. Docs are hosted at https://overlay-kit.slash.page. overlay-kit is published as the [`overlay-kit`](https://www.npmjs.com/package/overlay-kit) npm package. The public surface is small and intentionally stable: - ``: a context provider mounted once at the React root that determines where overlays render. - `overlay.open`, `overlay.openAsync`, `overlay.close`, `overlay.closeAll`, `overlay.unmount`, `overlay.unmountAll`: imperative API for opening and disposing overlays from inside or outside React (e.g., HTTP client hooks). - `useCurrentOverlay`, `useOverlayData`: hooks that expose the current top overlay id and the full registry of mounted overlays. The library is UI-library agnostic. There is no built-in dialog UI — you supply the component, overlay-kit manages mounting, async results, and lifecycle. Documentation is bilingual (English at `/en`, Korean at `/ko`); English is the default locale and the canonical content surfaced here. The project is MIT-licensed and developed openly in the [toss/overlay-kit](https://github.com/toss/overlay-kit) GitHub repository. ## Docs - [Getting Started](https://overlay-kit.slash.page/en/docs/guides/introduction): install, OverlayProvider setup, and a complete `overlay.open` / `overlay.openAsync` walkthrough. - [Think in overlay-kit](https://overlay-kit.slash.page/en/docs/guides/think-in-overlay-kit): rationale for the Declarative Overlay Pattern, imperative vs declarative comparison, and core design principles (Co-location, Minimum API). - [Code Comparison](https://overlay-kit.slash.page/en/docs/guides/code-comparison): before/after of overlay code with and without overlay-kit. - [Hooks](https://overlay-kit.slash.page/en/docs/guides/hooks): `useCurrentOverlay` returns the top overlay's id; `useOverlayData` returns the full `{ id, componentKey, isOpen, controller }` registry. - [Testing](https://overlay-kit.slash.page/en/docs/guides/testing): Jest/Vitest + React Testing Library recipes for closing overlays, multiple overlays, async results, `closeAll`/`unmountAll`, and hook-based state assertions. - [FAQ](https://overlay-kit.slash.page/en/docs/guides/faq): common questions about `open` vs `openAsync`, `close` vs `unmount`, supported UI libraries, TypeScript support, and animation handling. - [Opening Overlays](https://overlay-kit.slash.page/en/docs/more/basic): expanded examples of `overlay.open`, `overlay.openAsync`, and memory-release patterns (`onExit`, `setTimeout`). - [Opening Overlays Outside React](https://overlay-kit.slash.page/en/docs/more/open-outside-react): triggering overlays from non-React code, e.g., `ky` `afterResponse` hooks for global error dialogs. ## API - [``](https://overlay-kit.slash.page/en/api/components/overlay-provider): provider component; must be mounted exactly once at the application root. - [`overlay.open`](https://overlay-kit.slash.page/en/api/utils/overlay-open): `overlay.open(controller, options?)`. Returns the overlay id (string). `options.overlayId` allows specifying a custom id. - [`overlay.openAsync`](https://overlay-kit.slash.page/en/api/utils/overlay-open-async): `overlay.openAsync(controller, options?)`. Returns `Promise` resolved by the value passed to `close(value)`; the controller also receives `reject` to reject the Promise. - [`overlay.close`](https://overlay-kit.slash.page/en/api/utils/overlay-close): close a specific overlay by id; controller stays in memory so closing animations and state survive. - [`overlay.closeAll`](https://overlay-kit.slash.page/en/api/utils/overlay-close-all): close every open overlay; state stays in memory. - [`overlay.unmount`](https://overlay-kit.slash.page/en/api/utils/overlay-unmount): completely remove a specific overlay from the React tree and memory. - [`overlay.unmountAll`](https://overlay-kit.slash.page/en/api/utils/overlay-unmount-all): completely remove every overlay from the React tree and memory. ## Design system integrations - [Material UI](https://overlay-kit.slash.page/en/docs/more/with-design-systems/mui): MUI `Dialog` with `open`/`onClose`; pass `unmount` through `TransitionProps.onExited` to release memory after the exit animation. - [Chakra UI](https://overlay-kit.slash.page/en/docs/more/with-design-systems/chakra-ui): Chakra v3 `Dialog.Root` with `open`/`onOpenChange`; call `close()` on `!e.open` and schedule `setTimeout(unmount, 200)` to release memory after the ~200ms scale animation. - [Ant Design](https://overlay-kit.slash.page/en/docs/more/with-design-systems/ant-design): antd `Modal` with `open`/`onCancel`/`onOk`; pass `unmount` to `afterClose` to release memory after the close animation. ## Project - [GitHub repository](https://github.com/toss/overlay-kit): source code, issues, releases, changelog. - [Discord](https://discord.gg/vGXbVjP2nY): community chat. - [English README](https://github.com/toss/overlay-kit/blob/main/README.md): quick-start in English. - [Korean README](https://github.com/toss/overlay-kit/blob/main/README-ko_kr.md): quick-start in Korean. - [npm package](https://www.npmjs.com/package/overlay-kit): published versions and metadata. ## Optional - [Inlined full documentation](https://overlay-kit.slash.page/llms-full.txt): all guide, API, and integration pages concatenated into a single text file for LLM ingestion. - [Korean docs root](https://overlay-kit.slash.page/ko): the same documentation tree in Korean. - [DeepWiki](https://deepwiki.com/toss/overlay-kit): auto-generated wiki of the repository for codebase exploration. - [License](https://github.com/toss/overlay-kit/blob/main/LICENSE): MIT, © Viva Republica, Inc.