API Reference

Complete reference for all exported functions, components, hooks, and types.

---

Core Functions

alert(options)

Displays a notification modal. Returns a promise that resolves when the user closes the modal.

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)

Displays a confirmation modal. Returns a promise that resolves to true (confirmed) or false (cancelled).

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)

Displays an input modal. Returns a promise that resolves to the value entered by the user, or undefined if cancelled (unless returnOnCancel is set).

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

Must be mounted once at the app root. Initializes the modal service and provides configuration to all modal calls.

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?)

Returns alert, confirm, and prompt handlers tied to the component's lifecycle. All modals opened through this hook are automatically closed when the component unmounts.

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?)

Provides manual control over modal service initialization. Useful when you need to mount modals into a specific DOM container.

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

---

useActiveModalCount()

Returns the number of currently active (open) modals.

function useActiveModalCount(): number

---

useModalOptions()

Returns the current global modal configuration options.

function useModalOptions(): ConfigurationContextProps

---

useModalDuration()

Returns the modal animation duration from configuration.

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

---

useModalBackdrop()

Returns the modal backdrop CSS value from configuration.

function useModalBackdrop(): string | CSSProperties

---

useModalAnimation(visible, handlers)

Fires callbacks when the modal's visibility state changes. Use inside custom ForegroundComponent implementations to drive CSS transitions.

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

---

useDestroyAfter(modalId, delayMs)

Automatically destroys a modal after the specified delay. Used in custom foreground components (e.g., toast notifications).

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

---

useSubscribeModal(modal)

Subscribes to a modal node's state changes and returns the current version number. Causes the component to re-render when the modal updates.

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.