Modal

Generic modal shell for rich content, forms, and structured workflows. Use the more specialised components when the content fits their narrower contract.

Choosing this component

• Presenting rich or structured content (forms, multi-step wizards, detail views) inside a blocking overlay.
• Collecting structured input — especially when multiple fields or widgets are involved.
• Displaying content that requires user interaction before the page can continue, but where the interaction is more than a simple yes/no.

Choosing something else

• Two-action confirm/cancel prompts — use ConfirmDialog instead. It handles autofocus on the cancel button, aria-describedby, and the destructive-variant button automatically.
• Urgent blocking acknowledgements that must not be dismissed by Escape or backdrop click — use AlertDialog instead.
• Navigation — use a page transition or router link instead. Modals break the browser's back-button mental model.
• Persistent side content — use a Drawer or Sidebar so the content stays visible while the user works.
• Displaying information that does not require a decision — use a Popover or inline content instead.

Dialog model

Cinder provides three dialog-level components with distinct interaction contracts.

Modal is the generic shell. It handles focus capture/restore, body scroll lock, Escape dismissal, backdrop dismissal, and an optional close button. All three dismissal affordances are on by default (dismissOnBackdropClick, dismissOnEscape, closeButtonVisible). Use Modal when the content is richer than a simple prompt.

ConfirmDialog is a preset for user-initiated binary decisions. It composes Modal + two Buttons, defaults focus to the cancel button (the industry-standard guard against accidental destructive confirms), and wires aria-describedby automatically. Escape, backdrop click, and the close-X all fire onCancel. Use it for "Delete account?", "Discard changes?", and similar two-action prompts.

AlertDialog is a preset for urgent, blocking acknowledgements. It renders Modal with role="alertdialog", dismissOnBackdropClick={false}, dismissOnEscape={false}, and no close button. The user must click an explicit action button to proceed. Use it for session expiry and system-level errors — cases where the system surfaces a condition that must be acknowledged before continuing. For user-initiated actions (even high-impact ones), use ConfirmDialog instead.

The role prop and alertdialog

Modal accepts role="alertdialog" directly. This is intentional: some applications need to compose their own sticky dialog outside the AlertDialog preset (for example, a dialog with richer body content than AlertDialog's plain-text description prop allows).

When composing role="alertdialog" on Modal directly:

• Set dismissOnBackdropClick={false} and dismissOnEscape={false} — otherwise the urgent-blocking contract is broken.
• Set closeButtonVisible={false} — a close-X contradicts the "must acknowledge" intent.
• Pass describedById pointing at a descriptive element in the body — aria-describedby is required for alertdialog.

If the content fits the plain-text description constraint, prefer AlertDialog over composing Modal + role="alertdialog" manually.

Related components

• ConfirmDialog — pre-wired confirm/cancel variant built on Modal. Use for binary decisions.
• AlertDialog — sticky alert dialog that cannot be dismissed by Escape or backdrop click. Use for urgent acknowledgements.
• Drawer — side-anchored overlay for supplementary content.
• Sheet — bottom-anchored overlay for mobile-style interactions.
• Popover — non-blocking floating panel for contextual content.

Usage

<script lang="ts">
  import Modal from '@lostgradient/cinder/modal';
</script>

<Modal />