# Overlay-manager-rc
English | [한국어](./README.ko.md)
Inspired by [angular cdk overlay](https://material.angular.io/cdk/overlay/overview)
> React overlay component manager
## Feature
- (alert-dialog, dialog, sheet...) open, close state **no more management**.
- **You don't need to worry about declaring overlay component**. It's okay to have multiple overlays.
- Delivering data to overlay component props.
- Detect when an overlay component is closed; the resulting data is received on close.
- **Prevent closing with beforeClose logic.** **Asynchronous result handling with await.**
- **Simplified API with automatic ID management.**
- **No unnecessary renders when opening or closing overlay components.**
- **React 19 support**
## Install
npm
```shell
npm install overlay-manager-rc
```
yarn
```shell
yarn add overlay-manager-rc
```
pnpm
```shell
pnpm add overlay-manager-rc
```
## Setting
ex) nextjs(app router) + shadcn-ui(radix-ui)
already install
- alert-dialog
### Step1
make file `overlay-manager-provider.tsx`;
```typescript jsx
'use client';
import type { ReactNode } from 'react';
import { OverlayContainer } from "overlay-manager-rc";
export function OverlayContainerNext({ children }: { children?: ReactNode }) {
return ;
}
```
### Step2
set provider in `layout.tsx` component
```typescript jsx
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
## Usage
### Create overlay component
```typescript jsx
import type {OverlayContentProps} from 'overlay-manager-rc';
import {useBeforeClose} from 'overlay-manager-rc'; // Import useBeforeClose
export function TestContent({
open,
data,
close,
id // add id prop
}: OverlayContentProps) {
return (
{
!v && close();
}}
open={open}
>
Alert title
Get Data: {data}
Cancel
Continue
);
}
```
### Open overlay
```typescript jsx
'use client';
import { useOverlayManager } from 'overlay-manager-rc';
export function AlertSection() {
const { openOverlay } = useOverlayManager();
const handleOpenAlert = async () => {
const result = await openOverlay({
content: TestContent,
data: 'hello!!!!',
onClose: (result) => {
console.log('Dialog closed with result:', result);
},
onOpen: (id) => {
console.log('Overlay opened with id:', id);
},
});
console.log('Result from openOverlay:', result); // Same value as onClose result
};
return (
);
}
```
### Manual ID Management
When you specify a manual ID and an overlay with the same ID is already open, the existing overlay will automatically close before opening the new one.
```typescript jsx
'use client';
import { useOverlayManager } from 'overlay-manager-rc';
export function AlertSection() {
const { openOverlay } = useOverlayManager();
const handleOpenAlert = async () => {
// This will close any existing overlay with ID 'custom-alert'
// before opening the new one
await openOverlay({
id: 'custom-alert',
content: TestContent,
data: 'first alert!',
});
};
const handleOpenAnotherAlert = async () => {
// If 'custom-alert' is already open, it will close first
await openOverlay({
id: 'custom-alert',
content: TestContent,
data: 'second alert!',
});
};
return (
);
}
```
## API
### useOverlayManager
**returns**
| name | description | parameter |
| --- | --- | --- |
| openOverlay | Opens an overlay component. Returns a Promise. | OverlayOptions |
| closeAllOverlays | Closes all overlay components. | - |
| closeOverlayById | Closes an overlay component by ID. | id: string |
#### OverlayOptions
| Prop | Type | Default | Required |
| --- | --- | --- | --- |
| id | string | - | No |
| content | OverlayContent | - | Yes |
| data | TData | - | No |
| onClose | (result?: TResult) => void \| Promise | - | No |
| onOpen | (id: string) => void \| Promise | - | No |
| beforeClose | () => boolean \| Promise | - | No |
#### OverlayContentProps
| Prop | Type | Default | Required |
| --- | --- | --- | --- |
| data | TData | - | Yes |
| close | (result?: TResult) => void | - | Yes |
| open | boolean | - | Yes |
| id | string | - | Yes |
#### useBeforeClose
When the manager tries to run an overlay with the same id
function that executes before closing the overlay
```typescript jsx
import { useBeforeClose } from 'overlay-manager-rc/useBeforeClose';
// ... inside your overlay component
useBeforeClose(async () => {
// Your logic to determine whether to prevent closing.
// For example, check if a form is dirty.
const canClose = window.confirm('Are you sure you want to close?');
return canClose; // Return true to allow closing, false to prevent it.
}, id); // Pass the overlay's ID
```