\n\n## 💡 Why this library?\n\nIntroducing `async/await` to JavaScript was a major step forward: nested callback pyramids could be written in a linear, almost synchronous style, avoiding callback hell.\n\nWith React, Vue, and other MVVM frameworks, modals are usually controlled by `visible` / `open` props. A business flow like “open dialog → wait for user → continue based on result” is one logical sequence, but it gets split into:\n\n- Parent state for `visible` **and** for **payload passed into the modal** (props / context)\n- Follow-up logic inside `onOk` / `onCancel` / `onClose`, where the **return value** (form data, confirm choice) is delivered—not back to the function that opened the dialog\n- Multiple chained dialogs pushing logic into nested callbacks or ad-hoc state machines\n\n**Modal interaction became callback-driven again at the UI layer** (even when you do pass data in and get a result out of the modal UI itself).\n\n`use-modal-ref` brings **modal-driven workflows** back to `async/await`: callers `await modalRef.current.modal(...)`, components finish with `endModal` / `cancelModal`, so a full business path stays linear instead of being chopped into scattered handlers.\n\n### Flow comparison\n\n**Traditional approach: state + callbacks split the flow**\n\n```mermaid\nflowchart TD\n A[User clicks Submit] --> B[\"setPayload(order) + setVisible(true)\"]\n B --> C[Modal renders with props/data]\n C --> D{User action}\n D -->|OK| E[\"onOk(result) — return value arrives here only\"]\n D -->|Cancel| F[\"onCancel\"]\n E --> G[\"setVisible(false)\"]\n F --> G\n G --> H[\"Continue in onOk callback (save API / open next modal…)\"]\n H --> I[\"Next modal → another handler; caller cannot await a return value\"]\n```\n\n**With use-modal-ref: write the flow in order**\n\n```mermaid\nflowchart TD\n A[User clicks Submit] --> B[\"result = await modalRef.modal(data)\"]\n B --> C[Modal opens, Promise pending]\n C --> D{User action}\n D -->|OK| E[\"modal.endModal(result)\"]\n D -->|Cancel| F[\"modal.cancelModal()\"]\n E --> G[Promise resolves]\n F --> H[Promise rejects]\n G --> I[\"Code after await runs next\"]\n H --> I\n I --> J[\"await another modal in the same function linear end-to-end flow\"]\n```\n\n### Code comparison\n\n\nTraditional: visible state + callbacks\n\n```jsx\nfunction OrderPage() {\n const [confirmOpen, setConfirmOpen] = useState(false);\n const [editOpen, setEditOpen] = useState(false);\n const [confirmPayload, setConfirmPayload] = useState(null);\n const [editPayload, setEditPayload] = useState(null);\n const [draft, setDraft] = useState({ items: [] });\n\n const handleSubmit = () => {\n // Pass data in: stash payload, then open (not return values to this function)\n setConfirmPayload({ order: draft });\n setConfirmOpen(true);\n };\n\n const handleConfirmOk = async (confirmed) => {\n // Return value out: modal calls onOk with user input (or reads form ref inside)\n setConfirmOpen(false);\n setConfirmPayload(null);\n\n const saved = await saveOrder(confirmed);\n setEditPayload(saved);\n setEditOpen(true);\n };\n\n const handleEditOk = (edited) => {\n setEditOpen(false);\n setEditPayload(null);\n message.success('Done');\n };\n\n return (\n <>\n \n setConfirmOpen(false)}\n />\n setEditOpen(false)}\n />\n \n );\n}\n```\n\n> Traditional modals **can** pass parameters (props / state) and surface a result via `onOk`. What breaks the linear story is that `handleSubmit` **cannot** `await` that result—the next step must live in `handleConfirmOk`, then `handleEditOk`.\n\n\n\n\nuse-modal-ref: chain with await\n\n```jsx\nfunction OrderPage() {\n const confirmRef = useRef(null);\n const editRef = useRef(null);\n const [draft, setDraft] = useState(null);\n\n const handleSubmit = async () => {\n const ok = await confirmRef.current.modal({ order: draft });\n const saved = await saveOrder(ok);\n const edited = await editRef.current.modal(saved);\n message.success('Done');\n };\n\n return (\n <>\n \n \n \n \n );\n}\n```\n\n> On cancel, the modal calls `cancelModal()` and the Promise **rejects**—the `async` handler stops at that `await`; no `undefined` check needed.\n\n\n\n### When it helps\n\n- **Process-heavy** UX: wizards, confirm-then-edit, double confirm before delete\n- You want one **async function** for open → wait → branch → continue, not many `visible` flags and handlers\n- Imperative APIs (e.g. `showRefModal`) that still need an **awaitable result**\n\n> Note: Modal UI stays declarative (`visible` / `{...modal.props}`). This library changes how **callers structure business flow**—from callback-driven back to await-driven.\n\n## ✨ Features\n\n- 🎯 **Simple & Intuitive** - Easy-to-use hooks for modal/drawer management\n- 🔄 **Async/Await Support** - Return values from modals with Promise-based API\n- 🎨 **Framework Agnostic** - Works with any UI library (Antd, Material-UI, etc.)\n- 🔧 **Extensible** - Support custom modal types (Popover, Tooltip, etc.)\n- 📦 **Lightweight** - Minimal runtime deps (`@babel/runtime` only; React as peer), no UI library dependencies, TypeScript support\n- 🎭 **Multiple Usage Patterns** - Ref-based, function-based, and component-based approaches\n\n## 📦 Installation\n\n```bash\nnpm install use-modal-ref\n```\n\n```bash\nyarn add use-modal-ref\n```\n\n```bash\npnpm add use-modal-ref\n```\n\n### Local example (Playground)\n\nRunnable demo: [`examples/`](./examples) (**Vite + Ant Design 5**, sidebar + five README examples).\n\nDependencies and scripts live in the **root** `package.json`:\n\n```bash\nyarn install\nyarn demo\n```\n\n> Demo deps and scripts live in the root `package.json`. Vite aliases to `src/` for hot reload. Run `yarn build` and use `\"use-modal-ref\": \"file:..\"` to validate the npm package layout.\n\n### React version compatibility\n\n| Item | Notes |\n|------|-------|\n| **peerDependencies** | `react`, `react-dom` **>= 16.8.0** (minimum for Hooks) |\n| **Verified** | React **16** (unit tests), **18** (`examples` demo) |\n| **React 19** | Uses only stable Hooks APIs (`useState`, `useEffect`, `useMemo`, `useCallback`, `useImperativeHandle`); no legacy context or string refs. No known React 19 incompatibilities—please open an Issue if you hit one |\n| **Strict Mode** | Supported; demo runs inside `` |\n| **UI libraries** | Works with Ant Design, MUI, etc.; for Ant Design 5+, call `mergeModalType({ drawer: { visible: 'open', onClose: 'onClose' } })` at app entry |\n\n### Browser compatibility\n\nThe package ships **three JS builds**:\n\n| Entry / condition | Build | Format | Syntax target | Minimum (reference) |\n|-------------------|-------|--------|---------------|---------------------|\n| `import` (default) | `esm/` | **ESM** | ES6 | **Chrome ≥ 49** |\n| `require` (`main`) | `cjs/` | **CJS** | ES6 | **Chrome ≥ 49** |\n| `use-modal-ref/es` | `es/` | **ESM** | ES2020 | **Chrome ≥ 87** |\n\n```js\n// Default — Chrome ≥ 49 ESM (Vite / webpack / Rolldown)\nimport useModalRef from 'use-modal-ref';\n\n// Modern-only ESM entry\nimport useModalRef from 'use-modal-ref/es';\n\n// Node / older tooling\nconst useModalRef = require('use-modal-ref');\n```\n\n> CI validates builds with `es-check` (`esm/`+`cjs/` → ES6, `es/` → ES2020). Your bundler targets and polyfills still apply on top of these baselines.\n>\n> **Note:** `1.0.0` incorrectly published CJS under both `es/` and `esm/` while `exports.import` pointed at CJS; that broke default-import interop in Rolldown/Vite (`default is not a function`). Fixed in `1.0.1` with real ESM defaults that remain **Chrome ≥ 49**.\n\nFeature-specific Web APIs:\n\n| Feature | Required APIs |\n|---------|---------------|\n| Hooks (`useModalRef`, etc.) | React client runtime only — no DOM |\n| `createRefComponent` / `showRefModal` | DOM + `react-dom` |\n| `createUrlListener` / `getUrlListener` | `window` + History API by default; **`mergeNativeAdapter({ urlListener })`** for other runtimes |\n\n### Runtime: Web SSR / RSC / React Native\n\nHooks (`useModalRef` / `useDrawerRef` / `useCommonRef`) depend only on the **React client runtime** (`useState`, `useEffect`, etc.) and **do not touch** `window` / `document`. They work in **browsers, React Native**, and any client environment that supports Hooks.\n\n`createRefComponent` / `showRefModal` default to **DOM + react-dom** (mount adapter injectable). URL listening defaults to **History API** (noop without DOM). On React Native, use **`mergeNativeAdapter`** to declare capabilities (`null` = explicitly unsupported, `undefined` = keep Web default).\n\n**Server Components** (Next.js App Router) cannot use Hooks regardless of platform. The main entry is marked `'use client'` for framework boundaries.\n\n| API | Web browser | React Native | SSR / RSC |\n|-----|-------------|--------------|-----------|\n| `useModalRef` / `useDrawerRef` / `useCommonRef` | ✅ | ✅ (bind RN `Modal`, etc.) | ✅ in Client Components |\n| `createRefComponent` / `showRefModal` | ✅ | ✅ (`mergeNativeAdapter` / `createInTreeMountAdapter`) | ❌ without DOM + default adapter |\n| `createUrlListener` / `getUrlListener` | ✅ | ✅ (`mergeNativeAdapter({ urlListener })`) | default noop; `urlListener: null` = permanent noop |\n| `mergeModalType` | ✅ | ✅ | ✅ in Server Components |\n| `isBrowser()` | usually `true` | usually `false` | `false` on SSR |\n\n> `isBrowser()` means **DOM is available** (`window` + `document`), **not** “Hooks are allowed”. On React Native it is `false`, but Hooks still work.\n\n**React Native example (declarative modal + await):**\n\n```tsx\n// React Native only — for Web use antd / MUI (see Quick Start above)\nimport React from 'react';\nimport { Modal, View, Text, Button } from 'react-native';\nimport useModalRef from 'use-modal-ref';\n\nconst AppModal = React.forwardRef((_, ref) => {\n const { modal, data } = useModalRef(ref, { title: 'Hello' });\n\n return (\n \n \n {data.title}\n \n \n );\n});\n```\n\n**React Native / non-DOM: `mergeNativeAdapter`**\n\n```tsx\nimport {\n mergeNativeAdapter,\n createInTreeMountAdapter,\n showRefModal,\n} from 'use-modal-ref';\n\n// Declare native capabilities at startup (null = explicitly unsupported)\nmergeNativeAdapter({\n id: 'react-native',\n refComponentMount: myMountAdapter,\n urlListener: myUrlAdapter,\n});\n\nconst { adapter: inTreeAdapter, Host: RefMountHost } = createInTreeMountAdapter();\n\nfunction App() {\n useEffect(() => {\n mergeNativeAdapter({ refComponentMount: inTreeAdapter });\n return () => mergeNativeAdapter(null);\n }, []);\n\n return (\n <>\n \n \n \n );\n}\n```\n\nLegacy **`mergeRefComponentMount`** / **`mergeUrlListenerAdapter`** still work (they delegate to `mergeNativeAdapter`).\n\n**URL listener (`closeWhenUrlChange`):**\n\n```tsx\nimport { mergeNativeAdapter, showRefModal } from 'use-modal-ref';\n\nmergeNativeAdapter({\n urlListener: {\n id: 'react-navigation',\n createUrlListener: () => ({\n addListener(listener) {\n return navigation.addListener('state', () => listener(getCurrentRouteUrl()));\n },\n }),\n },\n});\n\nvoid showRefModal(MyModal, data, { closeWhenUrlChange: true, urlListenerAdapter: myAdapter });\n```\n\n**Next.js App Router example:**\n\n```tsx\n// app/layout.tsx — Server Component, global config only\nimport { mergeModalType } from 'use-modal-ref/config';\n\nmergeModalType({ drawer: { visible: 'open', onClose: 'onClose' } });\n```\n\n```tsx\n'use client';\n\nimport useModalRef from 'use-modal-ref';\n\nconst UserModal = React.forwardRef((_, ref) => {\n const { modal, data } = useModalRef(ref, { title: 'User' });\n return ;\n});\n```\n\n```tsx\n'use client';\n\nimport { showRefModal, isBrowser } from 'use-modal-ref';\n\nfunction Page() {\n const open = () => {\n if (!isBrowser()) return;\n void showRefModal(MyModal, { title: 'Hello' });\n };\n return ;\n}\n```\n\n> **React 16+**: `'use client'` is ignored as a plain string on React 16/17 (CRA, Vite, etc.). Environment checks use only `typeof window` / `typeof document` — no React 18+ APIs.\n\n## 🚀 Quick Start\n\n### Basic Modal Usage\n\n```jsx\nimport React, { useState, useRef } from 'react';\nimport { Modal, Button, Input } from 'antd';\nimport useModalRef from 'use-modal-ref';\n\n// Modal Component\nconst TestModal = React.forwardRef((props, ref) => {\n const [inputValue, setInputValue] = useState('');\n\n const { modal, data } = useModalRef(ref, {\n title: 'Default Title',\n label: 'Default Label'\n });\n\n const handleOK = () => modal.endModal(inputValue);\n const handleCancel = () => modal.cancelModal();\n\n return (\n Cancel,\n \n ]}\n >\n
\n );\n}\n```\n\n## 📚 Usage Examples\n\n### 1. Modal with Antd\n\nClick to expand\n\n```jsx\nimport React, { useState, useRef } from 'react';\nimport { Modal, Button, Input, Form } from 'antd';\nimport useModalRef from 'use-modal-ref';\n\nconst UserModal = React.forwardRef((props, ref) => {\n const [form] = Form.useForm();\n const [loading, setLoading] = useState(false);\n\n const { modal, data } = useModalRef(ref, {\n title: 'Add User',\n user: null\n }, {\n // You can perform initialization operations in this event, and the function's return value will be used as the new data returned from the useModalRef hook's data property\n beforeModal({ user }) {\n form.setFieldsValue(user || {\n name: '',\n email: '',\n });\n },\n // You can perform cleanup operations in this event, and the function's return value will be used as the new data returned from the useModalRef hook's data property.\n afterModalClose() {\n setLoading(false);\n form.setFieldsValue({\n name: '',\n email: '',\n });\n }\n });\n\n const handleSubmit = async () => {\n try {\n setLoading(true);\n const values = await form.validateFields();\n modal.endModal(values);\n } catch (error) {\n console.error('Validation failed:', error);\n } finally {\n setLoading(false);\n }\n };\n\n const handleCancel = () => modal.cancelModal();\n\n return (\n \n \n \n );\n});\n\n// Usage\nfunction UserManagement() {\n const userModalRef = useRef(null);\n\n const addUser = async () => {\n const userData = await userModalRef.current.modal({\n title: 'Add New User'\n });\n \n if (userData) {\n console.log('New user:', userData);\n // Handle user creation\n }\n };\n\n return (\n
\n \n \n
\n );\n}\n```\n\n\n\n\n### 2. Drawer with Antd\n\nBy default, the `drawer` type maps to `visible` + `onClose`, which matches **Ant Design 4** `Drawer`. \n**Ant Design 5+** uses `open` for visibility—call `mergeModalType` once at app entry (see example below).\n\n\nClick to expand\n\n```jsx\nimport React, { useState, useRef } from 'react';\nimport { Drawer, Button, Input, Space } from 'antd';\nimport { useDrawerRef, mergeModalType } from 'use-modal-ref';\n\n// Ant Design 5+: map drawer visibility to `open` (run once at app entry)\nmergeModalType({\n drawer: {\n visible: 'open',\n onClose: 'onClose',\n },\n});\n\nconst SettingsDrawer = React.forwardRef((props, ref) => {\n const [settings, setSettings] = useState({});\n\n const { modal, data } = useDrawerRef(ref, {\n title: 'Settings',\n initialSettings: {}\n }, {\n beforeModal: async (data) => {\n setSettings(data.initialSettings);\n return data;\n }\n });\n\n const handleSave = () => {\n modal.endModal(settings);\n };\n\n const handleCancel = () => {\n modal.cancelModal();\n };\n\n // modal.props maps to { open, onClose } after mergeModalType above\n return (\n \n \n \n \n }\n >\n \n setSettings(prev => ({ ...prev, setting1: e.target.value }))}\n />\n setSettings(prev => ({ ...prev, setting2: e.target.value }))}\n />\n \n \n );\n});\n\n// Usage\nfunction SettingsPage() {\n const settingsRef = useRef(null);\n\n const openSettings = async () => {\n const newSettings = await settingsRef.current.modal({\n title: 'Edit Settings',\n initialSettings: { setting1: 'value1', setting2: 'value2' }\n });\n \n if (newSettings) {\n console.log('Updated settings:', newSettings);\n }\n };\n\n return (\n
\n \n \n
\n );\n}\n```\n\n\n\n### 3. Custom overlay with explicit `modal.props` binding\n\nWhen your overlay is **not** Ant Design `Modal` / `Drawer` (or does not accept a single spread object), bind visibility and close explicitly instead of `{...modal.props}`:\n\n- `modal.props.visible` — whether the overlay is open\n- `modal.props.onCancel` — wired to `modal.cancelModal()` (the awaited `modal()` Promise **rejects** on cancel)\n\n> Runnable demo: `yarn demo` → **Modal props binding** (`examples/src/demos/ModalPropsBindingDemo.tsx`, component `examples/src/components/PropsBindingModal.tsx`).\n\n\nClick to expand\n\n```tsx\nimport React, { useRef, useState } from 'react';\nimport useModalRef, { ModalRef } from 'use-modal-ref';\n\ntype FormData = { title: string; hint: string };\n\n/** Custom overlay — only needs visible + onCancel from modal.props */\nfunction YourOverlay({\n visible,\n onCancel,\n title,\n onOk,\n children,\n}: {\n visible: boolean;\n onCancel: () => void;\n title: string;\n onOk?: () => void;\n children: React.ReactNode;\n}) {\n if (!visible) return null;\n return (\n
\n setValue(e.target.value)}\n onKeyDown={(e) => e.key === 'Enter' && handleOk()}\n />\n \n );\n});\n\nfunction Page() {\n const modalRef = useRef>(null);\n\n const openModal = async () => {\n try {\n const result = await modalRef.current!.modal({\n title: 'Edit',\n hint: 'Enter a value',\n });\n console.log('Result:', result);\n } catch {\n console.log('Cancelled');\n }\n };\n\n return (\n <>\n \n \n \n );\n}\n```\n\n**Notes:**\n\n- For built-in type `modal`, `modal.props` is `{ visible, onCancel }` by default — Ant Design users often use ``; custom overlays use the two fields above.\n- `ref.current.modal({ title: undefined })` does **not** overwrite `defaultData.title` (explicit `undefined` is skipped when merging open payload).\n- Confirm with `modal.endModal(value)`; cancel via overlay close / `modal.props.onCancel` → `cancelModal` → Promise rejection.\n\n\n\n### 4. JavaScript modal with JSDoc types\n\nIn `.js` projects, declare modal data and ref types with JSDoc and import `ModalRef` from the package — no `.ts` files required. IDE checks apply when `checkJs` is enabled in `jsconfig.json` / `tsconfig.json`.\n\n> Runnable demo: `yarn demo` → **7. JavaScript + JSDoc** (`#/usage/js-radio-modal`); sources `examples/src/components/RadioModal.js`, `examples/src/demos/JsRadioModalDemo.tsx`.\n\n\nClick to expand\n\n```jsx\n// RadioModal.js\nimport React, { useState } from 'react';\nimport { Modal, Radio } from 'antd';\nimport useModalRef from 'use-modal-ref';\n\n/**\n * @typedef {{\n * title?: string,\n * width?: number,\n * okText?: string,\n * message: Array<{\n * value: string,\n * text: string,\n * }>,\n * }} RadioModalData\n */\n\n/**\n * ModalRef — P: overlay type, T: data, U: result from endModal\n * @typedef {import('use-modal-ref').ModalRef<'modal', RadioModalData, string>} RadioModalRef\n */\n\nconst RadioModal = React.forwardRef(\n /**\n * @param {Record} props\n * @param {React.ForwardedRef} ref\n */\n (props, ref) => {\n /** @type {[string | null, React.Dispatch>]} */\n const [selectValue, setSelectValue] = useState(null);\n\n const {\n modal,\n data: { title, width, okText, message },\n } = useModalRef(ref, /** @type {RadioModalData} */ ({\n title: 'Notice',\n width: 560,\n okText: 'OK',\n message: [],\n }), {\n beforeModal({ message: options }) {\n setSelectValue(options[0]?.value ?? null);\n },\n });\n\n const handleOk = () => {\n if (selectValue != null) {\n modal.endModal(selectValue);\n }\n };\n\n return (\n \n setSelectValue(e.target.value)}\n >\n {message.map((item) => (\n {item.text}\n ))}\n \n \n );\n },\n);\n\nRadioModal.displayName = 'RadioModal';\nexport default RadioModal;\n```\n\n```jsx\n// Page.jsx — caller; import types from RadioModal.js via JSDoc import()\nimport React, { useRef } from 'react';\nimport { Button } from 'antd';\nimport RadioModal from './RadioModal';\n\nfunction Page() {\n /** @type {React.MutableRefObject} */\n const radioModalRef = useRef(null);\n\n const openRadio = async () => {\n try {\n const picked = await radioModalRef.current.modal(\n /** @type {import('./RadioModal').RadioModalData} */ ({\n title: 'Choose one',\n message: [\n { value: 'a', text: 'Option A' },\n { value: 'b', text: 'Option B' },\n ],\n }),\n );\n console.log('Picked:', picked);\n } catch {\n console.log('Cancelled');\n }\n };\n\n return (\n <>\n \n \n \n );\n}\n```\n\n**JSDoc checklist:**\n\n| Goal | Pattern |\n|------|---------|\n| Modal **data** shape | `@typedef { ... } RadioModalData` |\n| **Ref** type (data + result `U`) | `@typedef {import('use-modal-ref').ModalRef<'modal', RadioModalData, string>} RadioModalRef` |\n| `forwardRef` ref param | `@param {React.ForwardedRef} ref` |\n| `defaultData` literal | `/** @type {RadioModalData} */ ({ ... })` |\n| `useRef` in caller | `@type {React.MutableRefObject}` |\n| Reference **data** type in caller | `import('./RadioModal').RadioModalData` |\n\n> Pattern adapted from production `RadioModal.js`: define `@typedef` once in the modal component file; callers reference `import('./RadioModal').RadioModalRef` / `RadioModalData` without redeclaring.\n\n\n\n### 5. Custom Popover Component\n\n\nClick to expand\n\n```jsx\n// usePopoverRef.js\nimport { useCommonRef, mergeModalType } from 'use-modal-ref';\n\n// Register popover modal type\nmergeModalType({\n popover: {\n visible: 'visible',\n onClose: 'onClose',\n }\n});\n\nconst usePopoverRef = (ref, defaultData, options, deps = []) => \n useCommonRef('popover', ref, defaultData, options, deps);\n\nexport default usePopoverRef;\n```\n\n```jsx\n// ColorPickerPopover.jsx\nimport React, { useState } from 'react';\nimport { Popover, Button, Space } from 'antd';\nimport usePopoverRef from './usePopoverRef';\n\nconst ColorPickerPopover = React.forwardRef((props, ref) => {\n const [selectedColor, setSelectedColor] = useState('#1890ff');\n\n const { modal, data } = usePopoverRef(ref, {\n title: 'Choose Color',\n colors: ['#1890ff', '#52c41a', '#faad14', '#f5222d']\n });\n\n const handleColorSelect = (color) => {\n setSelectedColor(color);\n modal.endModal(color);\n };\n\n return (\n \n {data.colors.map(color => (\n handleColorSelect(color)}\n />\n ))}\n \n }\n >\n {props.children}\n \n );\n});\n\n// Usage\nfunction ColorPicker() {\n const colorRef = useRef(null);\n\n const pickColor = async () => {\n const color = await colorRef.current.modal({\n title: 'Select Color',\n colors: ['#1890ff', '#52c41a', '#faad14', '#f5222d', '#722ed1']\n });\n \n if (color) {\n console.log('Selected color:', color);\n }\n };\n\n return (\n
\n \n \n \n
\n );\n}\n```\n\n\n\n### 6. Function-based Modal\n\n\nClick to expand\n\n```jsx\nimport React from 'react';\nimport { Button } from 'antd';\nimport TestModal from './TestModal';\nimport { showRefModal } from 'use-modal-ref';\n\nfunction App() {\n const showModal = async () => {\n const result = await showRefModal(TestModal, {\n title: 'Dynamic Modal',\n label: 'This modal was created dynamically'\n });\n \n if (result) {\n alert(`Modal result: ${result}`);\n }\n };\n\n return (\n
\n \n
\n );\n}\n```\n\n\n\n### 7. Component-based Modal\n\n\nClick to expand\n\n```jsx\nimport React from 'react';\nimport { Button } from 'antd';\nimport TestModal from './TestModal';\nimport { createRefComponent } from 'use-modal-ref';\n\nfunction App() {\n const showModal = async () => {\n const [ref, destroy] = await createRefComponent(TestModal);\n \n try {\n const result = await ref.modal({\n title: 'Temporary Modal',\n label: 'This modal will be destroyed after use'\n });\n \n if (result) {\n alert(`Result: ${result}`);\n }\n } finally {\n destroy(); // Clean up the component\n }\n };\n\n return (\n
\n \n
\n );\n}\n```\n\n\n\n## 🔧 API Reference\n\n### useModalRef\n\n```typescript\nfunction useModalRef = {}>(\n ref: React.Ref,\n defaultData?: Partial | (() => Partial),\n options?: ModalRefOption<'modal', T, U, C>,\n deps?: React.DependencyList\n): {\n modal: ModalRef<'modal', T, U, C>;\n data: T;\n setData: (newData: T | ((data: T) => T)) => void;\n}\n```\n\n\n**Generic parameters:**\n\n- `T extends Record` - Shape of modal `data` (defaults to `any`)\n- `U = any` - Promise resolve type from `modal()`\n- `C extends Record = {}` - Type of custom properties in `options.custom`, merged onto `ModalRef`\n\n**Parameters:**\n\n- `ref: React.Ref` - React ref object for controlling modal show/hide. Must be passed to the modal component via `React.forwardRef`\n- `defaultData?: Partial | (() => Partial)` - Default data, can be an object or a function returning an object. When using a function, it supports lazy initialization and only executes when needed\n- `options?: ModalRefOption<'modal', T, U, C>` - Hook config and lifecycle callbacks; see [ModalRefOption](#modalrefoption)\n- `deps?: React.DependencyList` - When deps change, re-syncs lifecycle callbacks and `custom` internally (does not change `modal` identity; lifecycle hooks are not on the public `modal` API—configure them via `options`)\n\n**Returns:**\n\n- `modal: ModalRef<'modal', T, U, C>` - Modal control object with:\n - `visible: boolean` - Read-only visibility flag\n - `data: T` - Read-only current modal data\n - `props: { visible: boolean, onCancel: () => void }` - Spread onto Ant Design `Modal` (`visible` / `onCancel`)\n - `options: ModalRefOption<'modal', T, U, C>` - Read-only merged hook options\n - `modalOptions: ModalModalOptions` - Read-only runtime options from the latest `modal()` call\n - `modalPromise: Promise | null` - Read-only current Promise, `null` when closed\n - `modal(newData?: Partial, options?: ModalModalOptions): Promise` - Open modal and return Promise\n - `endModal(result?: U, onDone?: () => void): Promise` - Confirm close and resolve Promise\n - `cancelModal(ex?: any, onDone?: () => void): Promise` - Cancel; rejects unless `alwaysResolve` is set\n- `data: T` - Current modal data (same as `modal.data`)\n- `setData: (newData: T | ((data: T) => T)) => void` - Update modal data (object or updater)\n\n### ModalRefOption\n\nThe `options` parameter of `useModalRef`, `useDrawerRef`, and `useCommonRef` shares this type (generic `P` matches the overlay type).\n\n```typescript\ntype ModalRefOption<\n P extends ExtendedModalType,\n T extends Record,\n U,\n C extends Record = {},\n R = unknown\n> = {\n useImperativeHandle?: boolean;\n alwaysResolve?: boolean;\n visibleKey?: string;\n custom?: C;\n beforeModal?: (\n newData: Partial,\n pause: (result: any, isError?: boolean) => void,\n options: Record\n ) => void | Partial | Promise>;\n afterModal?: (newData: any, options?: ModalModalOptions) => void | Promise;\n init?: (newData: T, options: Record) => void | Promise;\n beforeCloseModal?: (\n next: (ok: any) => void,\n action: ModalAction,\n modal: ModalRef\n ) => void | Promise;\n afterCloseModal?: (\n newData: T,\n action: ModalAction,\n modal: ModalRef\n ) => void | Promise;\n [key: string]: any;\n}\n```\n\n**Properties:**\n\n> Lifecycle hooks (`beforeModal`, `afterModal`, etc.) are **configured via `options` only**—they are not part of the public `modal` / `ref.current` type.\n\n- `useImperativeHandle?: boolean` - Whether to expose `modal` on `ref` via `useImperativeHandle`. Defaults to `true` (only `false` disables it). **Treat as constant**—do not change at runtime after the first render\n- `alwaysResolve?: boolean` - When `true`, `cancelModal` resolves the Promise instead of rejecting\n- `visibleKey?: string` - Overrides the default visibility prop name from `modalTypeMap`, producing `modal.props.[visibleKey]`. For Ant Design 5 `Drawer`, use `'open'`; see [mergeModalType](#mergemodaltype) for global mapping\n- `custom?: C` - Custom properties merged onto `modal`, accessible via `modal.xxx` or `ref.current.xxx`. **Must not use built-in modal property names** (e.g. `modal`, `visible`, `endModal`, `beforeModal`); conflicting keys are ignored with a dev warning\n\n **custom example:**\n\n ```tsx\n import React, { useState, useRef } from 'react';\n import { Modal } from 'antd';\n import useModalRef, { ModalRef } from 'use-modal-ref';\n\n const TestModal = React.forwardRef((props, ref) => {\n const [formData, setFormData] = useState({});\n const resetForm = () => setFormData({});\n const validate = () => Object.keys(formData).length > 0;\n const { modal, data } = useModalRef<{ title: string }, any>(\n ref,\n { title: 'Default Title' },\n { custom: { resetForm, validate } }\n );\n return (\n \n \n \n );\n });\n\n function App() {\n const modalRef = useRef>(null);\n return (\n <>\n \n \n \n );\n }\n ```\n\n- `beforeModal?: (...)` - Pre-open hook. May return `Partial` to merge into data; call `pause(result, isError?)` to abort (`isError: true` throws)\n - `newData` - Data passed to this `modal()` call\n - `pause` - Abort/pause callback\n - `options` - Runtime options for this `modal()` call\n- `afterModal?: (newData, options?) => void | Promise` - **Post-open** hook (recommended). Hook-level `options.afterModal` and per-call `modal(data, { afterModal })` each fire **once** and do not replace each other\n- `init?: (newData, options) => void | Promise` - **Legacy** post-open callback (older API); kept for compatibility—**prefer `afterModal`** for new code. If both are set, `init` runs first, then `afterModal`\n- `beforeCloseModal?: (next, action, modal) => void | Promise` - Pre-close hook; call `next(false)` to prevent closing\n - `action` - `'end'` (confirm) or `'cancel'`\n- `afterCloseModal?: (newData, action, modal) => void | Promise` - Post-close hook; return value becomes new `data`\n\n### mergeModalType\n\nGlobally override prop field names on `modal.props` (visibility and close callback keys).\n\n```typescript\nfunction mergeModalType(map: Partial): MergeableModalTypeMap\n\ntype MergeModalTypeInput = Partial<{\n [K in keyof MergeableModalTypeMap]: ModalTypeItem;\n}>;\n```\n\n**Parameters:**\n\n- `map: Partial` - Partial map to merge. Covers built-in types and types registered via [module augmentation](#extending-overlay-types-module-augmentation). For Ant Design 5 `Drawer` using `open`:\n\n```typescript\nimport { mergeModalType } from 'use-modal-ref';\n\nmergeModalType({\n drawer: { visible: 'open', onClose: 'onClose' },\n});\n// All drawer instances then get modal.props { open, onClose }\n```\n\n> For a single hook instance only, set `options.visibleKey` instead of changing the global map.\n\n### useDrawerRef\n\n```typescript\nfunction useDrawerRef<\n T extends Record = any,\n U = any,\n C extends Record = {}\n>(\n ref: React.Ref,\n defaultData?: Partial | (() => Partial),\n options?: ModalRefOption<'drawer', T, U, C>,\n deps?: React.DependencyList\n): {\n modal: ModalRef<'drawer', T, U, C>;\n data: T;\n setData: (newData: T | ((data: T) => T)) => void;\n}\n```\n\n**Generic parameters:** Same `T`, `U`, `C` as [useModalRef](#usemodalref).\n\n**Parameters:**\n\n- `ref: React.Ref` - React ref for drawer show/hide\n- `defaultData?: Partial | (() => Partial)` - Default data (object or lazy factory)\n- `options?: ModalRefOption<'drawer', T, U, C>` - Hook config; see [ModalRefOption](#modalrefoption)\n- `deps?: React.DependencyList` - Re-sync `options` onto `modal` when deps change\n\n**Returns:**\n\n- `modal: ModalRef<'drawer', T, U, C>` - Drawer control object; default `modal.props` is `{ visible, onClose }` (map to `{ open, onClose }` via `mergeModalType` or `visibleKey`)\n- `data: T` - Current drawer data\n- `setData: (newData: T | ((data: T) => T)) => void` - Update drawer data\n\n> **With Ant Design Drawer:** Built-in `drawer` exposes `modal.props.visible` by default. Ant Design 5+ `Drawer` expects `open`—call `mergeModalType({ drawer: { visible: 'open', onClose: 'onClose' } })` at app entry, or set `visibleKey: 'open'` in hook `options` for a single instance.\n### useCommonRef\n\n```typescript\nfunction useCommonRef<\n P extends ModalType = ModalType,\n T extends Record = any,\n U = any,\n C extends Record = {}\n>(\n modalType: P,\n ref: React.Ref,\n defaultData?: Partial | (() => Partial),\n options?: ModalRefOption,\n deps?: React.DependencyList\n): {\n modal: ModalRef;\n data: T;\n setData: (newData: T | ((data: T) => T)) => void;\n}\n```\n\n**Generic parameters:**\n\n- `P extends ModalType` - Overlay type (`'modal'`, `'drawer'`, `'popover'`, or extended via `mergeModalType`)\n- `T`, `U`, `C` - Same as [useModalRef](#usemodalref)\n\n**Parameters:**\n\n- `modalType: P` - Overlay type identifier\n- `ref: React.Ref` - React ref for show/hide control\n- `defaultData?: Partial | (() => Partial)` - Default data (object or lazy factory)\n- `options?: ModalRefOption` - Hook config; see [ModalRefOption](#modalrefoption)\n- `deps?: React.DependencyList` - Re-sync `options` onto `modal` when deps change\n\n**Returns:**\n\n- `modal: ModalRef` - Overlay control object\n- `data: T` - Current data\n- `setData: (newData: T | ((data: T) => T)) => void` - Update data\n### showRefModal\n\n```typescript\nfunction showRefModal<\n M extends ModalRef,\n D extends M extends ModalRef ? D : Record,\n U extends M extends ModalRef ? U : any\n>(\n RefModal: React.ForwardRefExoticComponent>,\n modalData?: D,\n options?: {\n /** Component props */\n props?: Record;\n /** Method name to call modal, defaults to 'modal' */\n modalMethod?: string;\n /** Method name to cancel modal, defaults to 'cancelModal' */\n cancelMethod?: string;\n /** Modal options */\n modalOptions?: ModalModalOptions;\n /** Whether to automatically close modal when URL changes */\n closeWhenUrlChange?: boolean;\n /** Container selector */\n selector?: string;\n /** Container ID */\n id?: string;\n /** Container element or function returning container */\n container?: HTMLElement | null | (() => HTMLElement);\n /** Container class name */\n className?: string;\n /** Callback after ref is created */\n onRef?: (ref: any, destroy: () => void) => void;\n /** Callback before container is appended, return true to prevent auto append */\n onAppendContainer?: (container: HTMLElement) => void | boolean;\n /** Callback before container is removed, return true to prevent auto remove */\n onRemoveContainer?: (container: HTMLElement) => void | boolean;\n /** Callback before component is destroyed, return true to prevent auto destroy */\n onDestroyComponent?: (container: HTMLElement) => void | boolean;\n /** Destroy delay in milliseconds, defaults to 50 */\n destroyDelay?: number;\n }\n): Promise\n```\n\n**Parameters:**\n\n- `RefModal: React.ForwardRefExoticComponent>` - Modal component to display, must be wrapped with `React.forwardRef`\n- `modalData?: D` - Data to pass to the modal, will be passed as the first argument to the `modal` method\n- `options?: object` - Configuration options object with the following properties:\n - `props?: Record` - Props to pass to the component\n - `modalMethod?: string` - Method name to call modal, defaults to `'modal'`\n - `cancelMethod?: string` - Method name to cancel modal, defaults to `'cancelModal'`\n - `modalOptions?: ModalModalOptions` - Modal options, will be passed as the second argument to the `modal` method\n - `closeWhenUrlChange?: boolean` - Whether to automatically close modal when URL changes, defaults to `false`\n - `selector?: string` - Container selector for finding existing container element\n - `id?: string` - Container ID for finding or creating container element\n - `container?: HTMLElement | null | (() => HTMLElement)` - Container element or function returning container\n - `className?: string` - Container class name, only used when creating new container\n - `onRef?: (ref: any, destroy: () => void) => void` - Callback function after ref is created\n - `onAppendContainer?: (container: HTMLElement) => void | boolean` - Callback before container is appended to DOM, return `true` to prevent auto append\n - `onRemoveContainer?: (container: HTMLElement) => void | boolean` - Callback before container is removed from DOM, return `true` to prevent auto remove\n - `onDestroyComponent?: (container: HTMLElement) => void | boolean` - Callback before component is destroyed, return `true` to prevent auto destroy\n - `destroyDelay?: number` - Destroy delay in milliseconds, defaults to `50`\n\n**Returns:**\n\n- `Promise` - Returns modal result Promise, will be rejected if user cancels\n\n### createRefComponent\n\n```typescript\nfunction createRefComponent<\n T extends React.ForwardRefExoticComponent>,\n P extends T extends React.ForwardRefExoticComponent> ? P : never,\n R extends T extends React.ForwardRefExoticComponent> ? R : never\n>(\n RefComponent: T,\n props?: P | null,\n options?: {\n /** Container selector */\n selector?: string;\n /** Container ID */\n id?: string;\n /** Container element or function returning container */\n container?: HTMLElement | null | (() => HTMLElement);\n /** Container class name */\n className?: string;\n /** Callback after ref is created */\n onRef?: (ref: any, destroy: () => void) => void;\n /** Callback before container is appended, return true to prevent auto append */\n onAppendContainer?: (container: HTMLElement) => void | boolean;\n /** Callback before container is removed, return true to prevent auto remove */\n onRemoveContainer?: (container: HTMLElement) => void | boolean;\n /** Callback before component is destroyed, return true to prevent auto destroy */\n onDestroyComponent?: (container: HTMLElement) => void | boolean;\n /** Destroy delay in milliseconds, defaults to 50 */\n destroyDelay?: number;\n }\n): Promise<[ref: R, destroy: () => void]>\n```\n\n**Parameters:**\n\n- `RefComponent: T` - Component to create, must be wrapped with `React.forwardRef`\n- `props?: P | null` - Props to pass to the component\n- `options?: object` - Configuration options object with the following properties:\n - `selector?: string` - Container selector for finding existing container element. If found, will use that container; otherwise creates a new one\n - `id?: string` - Container ID for finding or creating container element. If found, will use that container; otherwise creates a new one and sets this ID\n - `container?: HTMLElement | null | (() => HTMLElement)` - Container element or function returning container. If provided, will use this container directly\n - `className?: string` - Container class name, only used when creating new container\n - `onRef?: (ref: any, destroy: () => void) => void` - Callback function after ref is created, receives ref object and destroy function\n - `onAppendContainer?: (container: HTMLElement) => void | boolean` - Callback function before container is appended to DOM, return `true` to prevent auto append to `document.body`\n - `onRemoveContainer?: (container: HTMLElement) => void | boolean` - Callback function before container is removed from DOM, return `true` to prevent auto remove\n - `onDestroyComponent?: (container: HTMLElement) => void | boolean` - Callback function before component is destroyed, return `true` to prevent auto call to `ReactDOM.unmountComponentAtNode`\n - `destroyDelay?: number` - Destroy delay in milliseconds, defaults to `50`. Used to delay destroy operation to avoid incomplete animations\n\n**Returns:**\n\n- `Promise<[ref: R, destroy: () => void]>` - Returns a Promise that resolves to a tuple:\n - `ref: R` - Component's ref object containing all methods and properties exposed by the component\n - `destroy: () => void` - Destroy function that will unmount the component and remove the container (if container was auto-created)\n\n### ModalRef\n\n`ModalRef` is the type definition for the modal control object, containing the following properties and methods:\n\n```typescript\ntype ModalRef<\n P extends ModalType = 'modal',\n T extends Record = Record,\n U = any,\n C extends Record = {}\n> = {\n /** Read-only property: whether modal is visible */\n readonly visible: boolean;\n /** Read-only property: current modal data */\n readonly data: Partial> & { [key: string]: any };\n /** Read-only property: props to pass to Modal/Drawer component */\n readonly props: ModalPropsTypeMap[P];\n /** Read-only property: current configuration options */\n readonly options: ModalRefOption;\n /** Read-only property: current modal options */\n readonly modalOptions: ModalModalOptions;\n /** Read-only property: current modal Promise */\n readonly modalPromise: null | Promise | PromiseLike;\n\n /** Opens modal and returns Promise */\n modal(newData: T, options?: ModalModalOptions): Promise;\n\n /** Ends modal and returns result */\n endModal: (result?: U, onDone?: () => void) => Promise;\n \n /** Cancels modal */\n cancelModal: (ex?: any, onDone?: () => void) => Promise;\n\n [key: string]: any;\n} & {\n [key in keyof C]: C[key];\n}\n```\n\n**Property Descriptions:**\n\n- `visible: boolean` - Read-only property indicating whether the modal is currently visible\n- `data: T` - Read-only property containing the current modal data object\n- `props: ModalPropsTypeMap[P]` - Read-only property returning appropriate props based on modal type:\n - For `'modal'` type: `{ visible: boolean, onCancel: () => void }`\n - For `'drawer'` type: `{ visible: boolean, onClose: () => void }` by default; use generic `VK` (e.g. `ModalRef<'drawer', T, U, C, 'open'>`) after `mergeModalType` or `visibleKey: 'open'`\n - For `'popover'` type: `{ visible: boolean, onClose: () => void }`\n- `options: ModalRefOption` - Read-only property containing current configuration options\n- `modalOptions: ModalModalOptions` - Read-only property containing current modal options\n- `modalPromise: Promise | null` - Read-only property containing current modal Promise, `null` if modal is not open\n\n**Method Descriptions:**\n\n- `modal(newData: T, options?: ModalModalOptions): Promise` - Method to open the modal\n - `newData: T` - New data to pass to the modal, will be merged with `defaultData`\n - `options?: ModalModalOptions` - Modal options with the following properties:\n - `modalDataEvent?: boolean` - **Legacy data-payload callbacks** (optional). When `true`, you may pass `onOK` / `onCancel` on the **`newData`** object of `modal(newData, { modalDataEvent: true })`:\n - On open, those keys are **removed from `data`** (so they are not rendered or serialized with business fields).\n - On **`endModal(value)`**, `onOK(value)` runs first; if it returns a value other than `undefined`, that becomes the **`await modal()` resolve value** (before `beforeEndModal`).\n - On **`cancelModal(reason)`**, `onCancel(reason)` runs similarly and may rewrite the **reject reason** (before `beforeCancelModal`).\n - Field names are **`onOK`** (capital `OK`) and **`onCancel`** — not Ant Design’s `onOk`.\n - **New code:** prefer `await modal()` + `beforeEndModal` / `beforeCancelModal` in `modal()` options; use `modalDataEvent` only when migrating old APIs that attached OK/Cancel handlers to the data payload.\n\n ```tsx\n const result = await modalRef.current!.modal(\n {\n title: 'Confirm',\n onOK: async (value) => `processed-${value}`,\n onCancel: async () => 'user aborted',\n },\n { modalDataEvent: true },\n );\n // endModal('x') → result is 'processed-x'\n // cancelModal() → Promise rejects with 'user aborted'\n ```\n - `afterModal?: (newData: any, options?: ModalModalOptions) => void | Promise` - Hook after modal opens\n - `beforeCloseModal?: (next: (ok: any) => void, action: ModalAction) => void | Promise` - Hook before close\n - `beforeEndModal?: ModalBeforeEndHandler` - Pre-end hook; may rewrite the resolved value. Receives current `U` from `endModal`, returns `U | undefined | void`\n - `beforeCancelModal?: (reason?: any) => Promise` - Hook before cancel, can modify cancel reason\n - `afterCloseModal?: (newData: any, action: ModalAction, modal: ModalRef) => void | Promise` - Hook after close\n - `forceVisible?: boolean` - Force show, even if another modal is already open\n - `alwaysResolve?: boolean` - Whether to always resolve the Promise\n - Returns `Promise`, resolves with result, rejects when cancelled\n- `endModal(result?: U, onDone?: () => void): Promise` - Ends the modal\n - `result?: U` - Result value to return\n - `onDone?: () => void` - Callback function after completion\n- `cancelModal(ex?: any, onDone?: () => void): Promise` - Cancels the modal\n - `ex?: any` - Cancel reason, defaults to `'cancel'`\n - `onDone?: () => void` - Callback function after completion\n\n### getUrlListener\n\nGets the URL listener instance for listening to browser URL changes.\n\n```typescript\nfunction getUrlListener(): UrlListener\n\ninterface UrlListener {\n addListener: (\n listener: (url: string) => void,\n options?: { once?: boolean }\n ) => () => void;\n}\n```\n\n**Returns:**\n\n- `UrlListener` - URL listener object with the following method:\n - `addListener(listener: (url: string) => void, options?: { once?: boolean }): () => void` - Adds a URL change listener\n - `listener: (url: string) => void` - Listener function called when URL changes, receives new URL as parameter\n - `options?: { once?: boolean }` - Options object, when `once` is `true`, listener executes only once\n - Returns a function to remove the listener\n\n**Usage Example:**\n\n```typescript\nimport { getUrlListener } from 'use-modal-ref';\n\nconst urlListener = getUrlListener();\n\n// Add listener\nconst removeListener = urlListener.addListener((url) => {\n console.log('URL changed to:', url);\n}, { once: true });\n\n// Remove listener\nremoveListener();\n```\n\n## 📘 TypeScript Support\n\nThis library is written in TypeScript and provides full type definitions out of the box.\n\n### Exported types\n\nKey types importable from `use-modal-ref`:\n\n| Type | Description |\n|------|-------------|\n| `ModalRef` | Six-parameter ref: overlay type, data, result, custom, visibility key, cancel reason |\n| `ModalRefOption` | Hook `options` |\n| `ModalModalOptions` | Runtime `modal()` options |\n| `UseCommonRefReturn` | Hook return value |\n| `ModalCustomMap` / `ResolveCustomMap` | Custom keys excluding builtins / inferred from options |\n| `ResolveVisibleKey` / `ExtractVisibleKey` | Infer props field from `options.visibleKey` literal |\n| `ModalBeforeEndHandler` / `ModalBeforeCancelHandler` | Typed before-end / before-cancel handlers |\n| `ExtendedModalType` / `ModalTypeRegistry` | Built-in + augmentable overlay types |\n| `MergeModalTypeInput` / `MergeableModalTypeMap` | `mergeModalType` input and map types |\n\n### Generics U / R / VK\n\n```tsx\n// U: endModal / modal() Promise result\nconst ref = useRef>(null);\nconst { modal } = useModalRef(ref, defaultData);\nawait modal.endModal({ ok: true });\n\n// R: beforeCancelModal return type\ntype CancelPayload = { code: number; message: string };\nconst cancelRef = useRef>(null);\nuseModalRef(cancelRef, defaultData);\n\n// VK: infer from options.visibleKey literal (ref VK must match inferred value)\nconst drawerRef = useRef>(null);\nconst { modal: drawer } = useDrawerRef(drawerRef, data, { visibleKey: 'open' });\nvoid drawer.props.open;\n```\n\n### Extending overlay types (module augmentation)\n\n```typescript\n// types/use-modal-ref.d.ts\nimport type { ModalTypeItem } from 'use-modal-ref';\n\ndeclare module 'use-modal-ref' {\n interface ModalTypeRegistry {\n sidePanel: ModalTypeItem;\n }\n}\n\n// app/setup.ts\nimport { mergeModalType, useCommonRef } from 'use-modal-ref';\n\nmergeModalType({\n sidePanel: { visible: 'show', onClose: 'hide' },\n});\n\nconst ref = React.createRef>();\nconst { modal } = useCommonRef('sidePanel', ref, { title: 'Panel' });\n```\n\n### Type Safety\n\n```tsx\ninterface ModalData {\n title: string;\n label: string;\n}\n\ninterface ModalResult {\n value: string;\n}\n\nconst TestModal = React.forwardRef((props, ref) => {\n const { modal, data } = useModalRef(ref, {\n title: 'Default Title',\n label: 'Default Label'\n });\n \n // TypeScript will ensure data conforms to ModalData\n // and modal callbacks return ModalResult\n});\n```\n\n### Strict Mode Support\n\nThe library fully supports React's strict mode and concurrent features.\n\n## ⚠️ Error Handling\n\nHandle potential errors in your modal interactions:\n\n```jsx\nconst showModal = async () => {\n try {\n const result = await modalRef.current.modal(data);\n if (result !== undefined) {\n // Handle success\n console.log('Modal result:', result);\n } else {\n // Handle cancel/dismiss\n console.log('Modal was cancelled');\n }\n } catch (error) {\n // Handle errors during modal operations\n console.error('Modal error:', error);\n }\n};\n```\n\n## ⚡ Performance Optimization\n\n### Dependency Array Usage\n\nUse the dependency array to optimize re-renders:\n\n```jsx\nconst { modal, data } = useModalRef(ref, defaultData, options, [dep1, dep2]);\n```\n\n### Lazy Initialization\n\nFor expensive initializations, use function form of defaultData:\n\n```jsx\nconst { modal, data } = useModalRef(ref, () => {\n // Expensive computation only runs when needed\n return {\n title: getLocalizedTitle(),\n items: generateInitialItems()\n };\n});\n```\n\n## 🎯 Advanced Features\n\n### Custom Modal Types\n\nRegister extended overlay types via `ModalTypeRegistry` augmentation + `mergeModalType` (see [module augmentation](#extending-overlay-types-module-augmentation)). You can also merge runtime aliases for built-in keys:\n\n```jsx\nimport { useCommonRef, mergeModalType } from 'use-modal-ref';\n\nmergeModalType({\n tooltip: {\n visible: 'open',\n onClose: 'onOpenChange',\n }\n});\n\nconst useTooltipRef = (ref, defaultData, options, deps = []) =>\n useCommonRef('tooltip' as any, ref, defaultData, options, deps);\n```\n\n### Before/After Hooks\n\n```jsx\nconst { modal, data } = useModalRef(ref, defaultData, {\n beforeModal: async (data) => {\n // Called before modal opens\n console.log('Opening modal with data:', data);\n return data; // Can modify data\n },\n afterModal: (result) => {\n // Called after modal closes\n console.log('Modal closed with result:', result);\n }\n});\n```\n\n## 🤝 Contributing\n\nWe welcome all contributions! Here's how you can help:\n\n1. **Report bugs** - Use the issue tracker to report bugs\n2. **Suggest features** - Propose new features or improvements\n3. **Submit PRs** - Fix bugs or implement new features\n\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## ❓ FAQ\n\n### Why use refs instead of state for modal control?\n\nRefs provide direct access to modal methods without triggering re-renders, making the API more efficient and easier to use.\n\n### How to handle multiple modals?\n\nEach modal should have its own ref:\n\n```jsx\nfunction App() {\n const modal1Ref = useRef(null);\n const modal2Ref = useRef(null);\n \n return (\n <>\n \n \n \n );\n}\n```\n\n### Can I use this with other UI libraries?\n\nYes! The library is UI-agnostic. Here's an example with Material-UI:\n\n```jsx\nimport { Dialog, DialogTitle, DialogContent } from '@mui/material';\nimport useModalRef from 'use-modal-ref';\n\nconst MaterialModal = React.forwardRef((props, ref) => {\n const { modal, data } = useModalRef(ref, { title: 'Dialog' });\n \n return (\n \n );\n};\n```\n\n","readmeFilename":"README.md"}