@ilokesto/modal

English | 한국어

A React modal package built on top of @ilokesto/overlay, following Grunfeld's awaitable dialog philosophy with smoother default motion.

@ilokesto/modal keeps modal policy inside the package: dismiss rules, focus handling, scroll lock, inline vs top-layer transport, backdrop behavior, and enter/exit animation. It uses @ilokesto/overlay only for presence lifecycle, so modal content can stay mounted during the closing phase and resolve after the exit motion finishes.

Documentation

• Full docs: English · 한국어
• Source: packages/modal
• npm: @ilokesto/modal

Features

• Awaitable modal flows — display() returns a Promise that resolves after exit animation
• Hook-based API — useModal() with display, close, closeAll, reject, remove, clear
• Global facade — modal and globalModalStore for module-level usage
• Provider-scoped stack policy — independent topness, z-index, dismiss, and focus policy per provider
• Inline transport — default fade/scale motion with full control
• Top-layer transport — native <dialog> with showModal()
• ESC and backdrop dismiss — light dismiss with onDismiss callback
• Focus management — auto-focus, focus restore, Tab focus trap (inline), native (top-layer)
• Scroll lock — reference-counted body scroll lock
• Positions — center, top, bottom, left, right, and corner variants
• Reduced motion — instant removal when prefers-reduced-motion: reduce
• closeAll — batch closing with exit animation
• reject — error flows via reject(id, reason) → Promise rejection
• onModalClose vs onDismiss — separate callbacks for any-close vs light-dismiss

Table of Contents

• Installation
• Basic Usage
• Close Lifecycle
• Global Facade
• Top-Layer Transport
• Accessibility
• Positioning
• Motion Model
• API Reference
• Source Layout
• Development
• License

Installation

pnpm add @ilokesto/modal react

or

npm install @ilokesto/modal react

Basic Usage

Modal content is provided through render. The render callback receives a close(result) function scoped to that specific modal instance, plus context for that modal. Use render: () => ... for static content too.

import { ModalProvider, useModal } from '@ilokesto/modal';

function ConfirmContent({
  onConfirm,
  onCancel,
}: {
  onConfirm: () => void;
  onCancel: () => void;
}) {
  return (
    <div
      style={{
        minWidth: 320,
        padding: 24,
        borderRadius: 16,
        background: '#ffffff',
        boxShadow: '0 24px 80px rgba(0, 0, 0, 0.24)',
      }}
    >
      <h2>Delete item?</h2>
      <p>This action cannot be undone.</p>
      <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
        <button onClick={onCancel}>Cancel</button>
        <button onClick={onConfirm}>Delete</button>
      </div>
    </div>
  );
}

function DeleteButton() {
  const { display } = useModal();

  const handleClick = async () => {
    const confirmed = await display<boolean>({
      id: 'delete-confirm',
      position: 'center',
      dismissible: true,
      ariaLabelledBy: 'delete-confirm-title',
      ariaDescribedBy: 'delete-confirm-description',
      render: (close) => (
        <ConfirmContent
          onConfirm={() => close(true)}
          onCancel={() => close(false)}
        />
      ),
    });

    console.log(confirmed);
  };

  return <button onClick={handleClick}>Open modal</button>;
}

export function App() {
  return (
    <ModalProvider>
      <DeleteButton />
    </ModalProvider>
  );
}

Close Lifecycle

Use onModalClose(result) when you need a callback whenever the modal is closed. Calling the scoped close(result) from render triggers that modal's callback once with the same result. Calling clear() triggers onModalClose for every open modal in stack order before removing them.

onDismiss is narrower: it only fires when a dismissible modal is dismissed by ESC or backdrop click.

closeAll and onModalClose

closeAll() transitions all open modals to closing without setting closeResult. The lifecycle store does not fire onModalClose during closeAll() itself. However, when the adapter subsequently calls remove(id) for each modal (after exit animation), onModalClose(undefined) fires indirectly because closeResult is undefined.

| Sequence | onModalClose argument | |---|---| | close(id, result) → remove(id) | result | | closeAll() → remove(id) | undefined | | remove(id) (without close) | undefined | | clear() | closeResult or undefined |

If you need to distinguish batch-close from individual-close in onModalClose, check a flag before calling closeAll() or use a separate onDismiss handler.

reject

reject(id, reason) transitions a modal to closing (same as close), but when the adapter later calls remove(id), the display() Promise is rejected with the reason. onModalClose also fires with undefined (reject is a close path).

Global Facade

If you prefer a module-level API, mount a default ModalProvider once and then use the exported modal facade.

Only one provider without a store is supported. Every default provider shares globalModalStore, so mounting more than one does not create independent facade stacks. For multiple simultaneous providers, pass a distinct overlay store to each ModalProvider; each provider then owns its own modal stack policy for inline and top-layer transports.

import { ModalProvider, modal } from '@ilokesto/modal';

function App() {
  return <ModalProvider>{/* your app */}</ModalProvider>;
}

async function openGlobalConfirm() {
  const result = await modal.display<boolean>({
    id: 'global-confirm',
    render: (close) => (
      <div>
        <button onClick={() => close(true)}>Confirm</button>
        <button onClick={() => close(false)}>Cancel</button>
      </div>
    ),
  });

  return result;
}

// Also available: modal.close, modal.closeAll, modal.reject, modal.remove, modal.clear

Top-Layer Transport

Inline transport is the default because it gives the package tighter control over animation and backdrop behavior.

When you want native top-layer rendering, use:

await display({
  id: 'settings-dialog',
  transport: 'top-layer',
  render: (close) => <SettingsDialog onClose={() => close()} />,
});

This path uses the native <dialog> element under the hood.

Accessibility

Always give modal content an accessible name. The preferred pattern is to render a visible heading and connect it with ariaLabelledBy; add ariaDescribedBy when helper text explains the consequence of the action.

await display({
  id: 'delete-confirm',
  ariaLabelledBy: 'delete-confirm-title',
  ariaDescribedBy: 'delete-confirm-description',
  render: (close) => (
    <section>
      <h2 id="delete-confirm-title">Delete item?</h2>
      <p id="delete-confirm-description">This action cannot be undone.</p>
      <button onClick={() => close(false)}>Cancel</button>
      <button onClick={() => close(true)}>Delete</button>
    </section>
  ),
});

For dialogs without a visible title, use ariaLabel. Use role: 'alertdialog' only for urgent confirmation flows that require immediate attention.

Autofocus in both transports and inline Tab wrapping use eligible controls in DOM order, excluding hidden, inert, CSS-hidden, disabled, and negative-tabIndex controls. With no eligible control, focus falls back to the panel or dialog. Native <dialog> retains its own keyboard containment. See the focus candidate contract for ancestor visibility and native inert behavior.

React Compiler note

The render callback must stay pure. Do not call hooks, create nested components, mutate captured values, or run side effects directly inside it. If the modal body needs hooks, return a real component and pass close as a prop.

// Good: hooks live inside SettingsDialog, not inside the render callback.
await display({
  ariaLabel: 'Settings',
  render: (close) => <SettingsDialog onClose={() => close()} />,
});

// Avoid: hooks inside render callbacks violate the Rules of Hooks.
await display({
  ariaLabel: 'Settings',
  render: (close) => {
    // const value = useSomething(); // Do not do this.
    return <SettingsDialog onClose={() => close()} />;
  },
});

Positioning

Supported position values:

• center
• top
• bottom
• left
• right
• top-left
• top-right
• bottom-left
• bottom-right

Motion Model

@ilokesto/modal uses the overlay closing state instead of removing immediately.

• open → fade in + scale in
• close → fade out + scale out
• remove → after exit animation completes
• reduced motion → removal is fast-tracked instead of waiting for animation

That means awaited results resolve after the modal is actually removed, not at the first close request.

API Reference

ModalProvider

Context provider. Wraps OverlayProvider from @ilokesto/overlay, registers the modal adapter, injects shared CSS, and owns the internal stack runtime used by both transports. Props: children, store?.

useModal()

Returns { display, close, closeAll, reject, remove, clear }.

• display<TResult>(options) — opens a modal, returns Promise<TResult | undefined>
• close(id, result?) — transitions modal to closing with result
• closeAll() — transitions all open modals to closing
• reject(id, reason?) — transitions modal to closing, Promise rejects on remove
• remove(id?) — removes modal from store (resolves/rejects Promise)
• clear() — removes all modals immediately

modal (facade)

Module-level API. Same methods as useModal() plus open(options) which returns id only.

globalModalStore

The pre-created lifecycle store. Can be passed as <ModalProvider store={...}> for custom integrations.

Types

• ModalProviderProps, UseModalOptions, ModalFacadeOptions
• ModalProps, ModalAdapterProps, ModalPosition
• ModalClose, ModalCloseHandler, ModalRender, ModalRenderContext

Source Layout

src/
  adapters/
    ModalAdapter.tsx
    ModalAdapterInline.tsx
    ModalAdapterTopLayer.tsx
  components/
    ModalProvider.tsx
  core/
    createModalStackRuntime.ts
  facade/
    modalFacade.ts
  hooks/
    useIsTopModal.ts
    useModal.ts
    useModalExit.ts
    usePrefersReducedMotion.ts
  shared/
    ModalStackRuntimeContext.ts
    animationDuration.ts
    getFocusableElements.ts
    lifecycle.ts
    styles.ts
    types.ts
  index.ts

Responsibilities

src/adapters — rendering:

• ModalAdapter.tsx — selects inline vs top-layer transport
• ModalAdapterInline.tsx — inline modal: backdrop, scroll lock, focus, dismiss, positioning, animation
• ModalAdapterTopLayer.tsx — native <dialog>: cancel/backdrop handling, positioning, scoped backdrop, animation

src/components — provider:

• ModalProvider.tsx — wraps OverlayProvider, owns modal stack policy, registers adapter, injects CSS, defaults to global store

src/facade — module-level API:

• modalFacade.ts — modal facade and globalModalStore

src/core — provider-local stack state:

• createModalStackRuntime.ts — token-based registration, order, topness, version notifications and target membership; no React imports

src/hooks — React hooks:

• useModal.ts — command API (display, close, closeAll, reject, remove, clear)
• useIsTopModal.ts — registers entries and subscribes to the provider's stack runtime
• useModalExit.ts — reduced-motion removal, exit-animation guard and fallback timer cleanup
• usePrefersReducedMotion.ts — prefers-reduced-motion detection with legacy fallback

src/shared — internal:

• ModalStackRuntimeContext.ts — React context connecting the provider and stack hooks
• getFocusableElements.ts — shared focus candidate selector, filtering and DOM order
• animationDuration.ts — existing inline animation duration and fallback delay rules
• lifecycle.ts — createModalLifecycleStore wrapping OverlayStoreApi with onModalClose injection
• styles.ts — shared fade/scale animation keyframes
• types.ts — modal props, render callback, adapter props, position contracts

Reading a modal operation

Start at ModalProvider for ownership, then createModalStackRuntime for stack changes and useIsTopModal for React subscription. Each adapter retains its transport policy: inline owns scroll locking, focus trapping and document events; top-layer owns showModal, native cancel and backdrop geometry.

Both adapters use useModalExit for when to finish closing. Inline supplies remove; top-layer closes its native dialog before calling remove. Shared timing does not merge the transports' focus or dismissal behavior. Markup, position styles, callback order and public exports stay unchanged.

Exports

• values → ModalProvider, useModal, modal, globalModalStore
• types → ModalProviderProps, UseModalOptions, ModalFacadeOptions, ModalProps, ModalAdapterProps, ModalPosition, ModalClose, ModalCloseHandler, ModalRender, ModalRenderContext

Development

pnpm install
pnpm run build
pnpm run typecheck
pnpm test

Build outputs are generated in the dist directory. Tests run with Vitest and @testing-library/react. E2E and a11y tests use Playwright.

License

MIT