API Reference

내보낸 모든 함수, 컴포넌트, 훅, 타입에 대한 전체 레퍼런스입니다.

---

Core Functions

alert(options)

알림 모달을 표시합니다. 사용자가 모달을 닫으면 resolve되는 프로미스를 반환합니다.

function alert<B = any>(options: AlertProps<B>): Promise<void>

AlertProps

Property	Type	Default	Description
title	ReactNode	—	Modal title
subtitle	ReactNode	—	Modal subtitle
content	ReactNode | ComponentType<AlertContentProps>	—	Modal body content
subtype	'info' | 'success' | 'warning' | 'error'	—	Semantic type passed to components
footer	AlertFooterRender | { confirm?: ReactNode; hideConfirm?: boolean } | false	—	Footer config; false hides footer
background	ModalBackground<B>	—	Data passed to BackgroundComponent
dimmed	boolean	—	Whether to dim backdrop
duration	number	—	Per-modal animation duration override (ms)
manualDestroy	boolean	false	If true, modal is not destroyed automatically after closing animation
closeOnBackdropClick	boolean	true	Close when backdrop is clicked
group	string	—	Group identifier for ordering
handleResolve	(result: void | null) => void	—	Called when promise resolves
ForegroundComponent	ComponentType<PropsWithChildren<ModalFrameProps>>	—	Per-modal foreground override
BackgroundComponent	ComponentType<ModalFrameProps>	—	Per-modal background override

await alert({
  title: 'Success',
  content: 'Item saved.',
  subtype: 'success',
  footer: { confirm: 'OK' },
});

---

confirm(options)

확인 모달을 표시합니다. 확인 시 true, 취소 시 false로 resolve되는 프로미스를 반환합니다.

function confirm<B = any>(options: ConfirmProps<B>): Promise<boolean>

ConfirmProps extends AlertProps with:

Property	Type	Default	Description
footer	ConfirmFooterRender | FooterOptions | false	—	Footer config

FooterOptions

interface FooterOptions {
  confirm?: ReactNode;
  hideConfirm?: boolean;
  cancel?: ReactNode;
  hideCancel?: boolean;
}

const confirmed = await confirm({
  title: 'Delete item',
  content: 'This cannot be undone.',
  footer: { confirm: 'Delete', cancel: 'Cancel' },
});
if (confirmed) await deleteItem();

---

prompt<T>(options)

입력 모달을 표시합니다. 사용자가 입력한 값으로 resolve되거나, 취소 시 undefined를 반환합니다 (returnOnCancel 설정 시 기본값 반환).

function prompt<T, B = any>(options: PromptProps<T, B>): Promise<T | undefined>

PromptProps<T> extends AlertProps with:

Property	Type	Default	Description
Input	(props: PromptInputProps<T>) => ReactNode	required	Input component renderer
defaultValue	T	—	Initial value
disabled	(value: T | undefined) => boolean	—	Disables confirm button when returns true
returnOnCancel	boolean	false	If true, resolves with defaultValue on cancel
footer	PromptFooterRender<T> | FooterOptions | false	—	Footer config

PromptInputProps<T>

interface PromptInputProps<T, Context = object> {
  value?: T;
  defaultValue?: T;
  onChange: (value: T | undefined) => void;
  onConfirm: () => void;
  onCancel: () => void;
  context: Context;
}

const name = await prompt<string>({
  title: 'Enter name',
  defaultValue: '',
  Input: ({ value, onChange }) => (
    <input value={value ?? ''} onChange={e => onChange(e.target.value)} />
  ),
  disabled: value => !value || value.length < 2,
});

---

Components

ModalProvider

앱 루트에 한 번만 마운트해야 합니다. 모달 서비스를 초기화하고 모든 모달 호출에 설정을 제공합니다.

import { ModalProvider, type ModalProviderProps, type ModalProviderHandle } from '@lerx/promise-modal';

Props (ModalProviderProps)

Prop	Type	Description
ForegroundComponent	ComponentType<PropsWithChildren<ModalFrameProps>>	Global modal container/card component
BackgroundComponent	ComponentType<ModalFrameProps>	Global backdrop component
TitleComponent	ComponentType<WrapperComponentProps>	Global title wrapper
SubtitleComponent	ComponentType<WrapperComponentProps>	Global subtitle wrapper
ContentComponent	ComponentType<WrapperComponentProps>	Global content wrapper
FooterComponent	ComponentType<FooterComponentProps>	Global footer component
options	ModalOptions	Global defaults for all modals
context	Record<string, any>	Arbitrary data passed to every component slot
usePathname	() => { pathname: string }	Custom hook for route-aware modal cleanup
root	HTMLElement | null	DOM element to mount modals into

Handle (ModalProviderHandle) — accessed via ref:

interface ModalProviderHandle {
  initialize: (element: HTMLElement) => void;
}

const ref = useRef<ModalProviderHandle>(null);
// Mount modals into a specific DOM node:
ref.current?.initialize(containerElement);

<ModalProvider ref={ref}>...</ModalProvider>

---

Hooks

useModal(configuration?)

컴포넌트 라이프사이클에 연동된 alert, confirm, prompt 핸들러를 반환합니다. 이 훅을 통해 열린 모든 모달은 컴포넌트가 언마운트될 때 자동으로 닫힙니다.

function useModal(configuration?: OverridableHandleProps): {
  alert: <B>(options: AlertProps<B>) => Promise<void>;
  confirm: <B>(options: ConfirmProps<B>) => Promise<boolean>;
  prompt: <T, B>(options: PromptProps<T, B>) => Promise<T | undefined>;
}

The optional configuration object provides default values merged into every call from this hook instance.

---

useInitializeModal(options?)

모달 서비스 초기화를 수동으로 제어합니다. 특정 DOM 컨테이너에 모달을 마운트해야 할 때 유용합니다.

function useInitializeModal(options?: { mode?: 'auto' | 'manual' }): {
  initialize: (element: HTMLElement) => void;
  portal: ReactNode;
}

---

useActiveModalCount()

현재 활성화된(열린) 모달의 수를 반환합니다.

function useActiveModalCount(): number

---

useModalOptions()

현재 전역 모달 설정 옵션을 반환합니다.

function useModalOptions(): ConfigurationContextProps

---

useModalDuration()

설정에서 모달 애니메이션 시간을 반환합니다.

function useModalDuration(): {
  duration: string;     // CSS duration string, e.g. '250ms'
  milliseconds: number; // numeric value, e.g. 250
}

---

useModalBackdrop()

설정에서 모달 백드롭 CSS 값을 반환합니다.

function useModalBackdrop(): string | CSSProperties

---

useModalAnimation(visible, handlers)

모달의 가시성 상태가 변경될 때 콜백을 실행합니다. CSS 트랜지션을 구동하기 위해 커스텀 ForegroundComponent 구현 내에서 사용하세요.

function useModalAnimation(
  visible: boolean,
  handlers: {
    onVisible?: () => void;
    onHidden?: () => void;
  }
): void

---

useDestroyAfter(modalId, delayMs)

지정된 지연 시간 후 모달을 자동으로 제거합니다. 커스텀 foreground 컴포넌트(예: 토스트 알림)에서 사용합니다.

function useDestroyAfter(modalId: number, delayMs: number): void

---

useSubscribeModal(modal)

모달 노드의 상태 변경을 구독하고 현재 버전 번호를 반환합니다. 모달이 업데이트될 때 컴포넌트를 리렌더링합니다.

function useSubscribeModal(modal: ModalNode): number

---

Types

ModalFrameProps<Context, B>

Props received by ForegroundComponent and BackgroundComponent.

interface ModalFrameProps<Context = object, B = any> {
  id: number;
  type: 'alert' | 'confirm' | 'prompt';
  alive: boolean;
  visible: boolean;
  initiator: string;
  manualDestroy: boolean;
  closeOnBackdropClick: boolean;
  background?: ModalBackground<B>;
  onConfirm: () => void;
  onClose: () => void;
  onChange: (value: any) => void;
  onDestroy: () => void;
  onChangeOrder: () => void;
  context: Context;
}

FooterComponentProps<Context>

Props received by FooterComponent.

interface FooterComponentProps<Context = object> {
  confirmLabel?: ReactNode;
  hideConfirm?: boolean;
  cancelLabel?: ReactNode;
  hideCancel?: boolean;
  disabled?: boolean;
  onConfirm: () => void;
  onCancel?: () => void;
  context: Context;
}

WrapperComponentProps<Context>

Props received by TitleComponent, SubtitleComponent, ContentComponent.

type WrapperComponentProps<Context = object> = PropsWithChildren<{
  context: Context;
}>;

ModalBackground<B>

interface ModalBackground<B> {
  data?: B;
}

ModalOptions

interface ModalOptions {
  zIndex?: number;
  duration?: number | string;
  backdrop?: string | CSSProperties;
  manualDestroy?: boolean;
  closeOnBackdropClick?: boolean;
}

AlertContentProps, ConfirmContentProps, PromptContentProps

Props received by a content component when passed as a ComponentType.

// AlertContentProps
type AlertContentProps<Context = object> = {
  onConfirm: () => void;
  context: Context;
};

// ConfirmContentProps
type ConfirmContentProps<Context = object> = {
  onConfirm: () => void;
  onCancel: () => void;
  context: Context;
};

// PromptContentProps = ConfirmContentProps

AI Agent Reference

AI Agent Reference — Full API Signatures

Exports

// Core functions (usable outside React)
export function alert<B = any>(options: AlertProps<B>): Promise<void>
export function confirm<B = any>(options: ConfirmProps<B>): Promise<boolean>
export function prompt<T, B = any>(options: PromptProps<T, B>): Promise<T | undefined>

// Provider
export const ModalProvider: ForwardRefExoticComponent<ModalProviderProps & RefAttributes<ModalProviderHandle>>
export type ModalProviderProps = BootstrapProviderProps
export interface ModalProviderHandle { initialize: (element: HTMLElement) => void }

// Hooks
export function useModal(configuration?: OverridableHandleProps): { alert, confirm, prompt }
export function useInitializeModal(options?: { mode?: 'auto' | 'manual' }): { initialize, portal }
export function useActiveModalCount(): number
export function useModalOptions(): ConfigurationContextProps
export function useModalDuration(): { duration: string; milliseconds: number }
export function useModalBackdrop(): string | CSSProperties
export function useModalAnimation(visible: boolean, handlers: { onVisible?(); onHidden?() }): void
export function useDestroyAfter(modalId: number, delayMs: number): void
export function useSubscribeModal(modal: ModalNode): number

// Types
export type { ModalOptions, ModalFrameProps, FooterComponentProps, ModalBackground }
export type { PromptInputProps, AlertContentProps, ConfirmContentProps, PromptContentProps }
export type { WrapperComponentProps }

BaseModal fields (shared by alert/confirm/prompt)

interface BaseModal<T, B> {
  group?: string;
  title?: ReactNode;
  subtitle?: ReactNode;
  background?: ModalBackground<B>;   // { data?: B }
  dimmed?: boolean;
  duration?: number;
  manualDestroy?: boolean;
  closeOnBackdropClick?: boolean;
  handleResolve?: (result: T | null) => void;
  ForegroundComponent?: ComponentType<PropsWithChildren<ModalFrameProps>>;
  BackgroundComponent?: ComponentType<ModalFrameProps>;
}

Key behavioral rules

• alert resolves void when any close action fires.
• confirm resolves true on confirm, false on cancel or backdrop click.
• prompt resolves the current input value on confirm, undefined on cancel (or defaultValue if returnOnCancel: true).
• manualDestroy: true keeps the modal node alive after onClose; the caller must call onDestroy to remove it from the DOM.
• Static alert/confirm/prompt are singletons that persist across component unmounts. useModal variants are closed on unmount.
• Custom ForegroundComponent receives visible (boolean) for driving enter/exit animations and onDestroy for deferred cleanup.