Modal
Accessible dialog overlay using native <dialog> element
Category: overlay · WCAG 2.2-AA · overlay, dialog, popup, ai
Sizes
- sm
- md
- lg
States
- closed
- open
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Whether the component is open (controlled). |
onClose | () => void | — | Called when the component is closed. |
title | string | — | Title text for the component. |
description | string | — | Supporting description text. |
size | 'sm' | 'md' | 'lg' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
footer | ReactNode | — | Dialog actions, rendered in a right-aligned row below the body and separated by a divider. |
draggable | boolean | false | Allow dragging the dialog by its header |
ai | boolean | 'generating' | false | AI presence: `true` gives the surface an AI-tinted edge and a soft aura, marking AI-generated content; `'generating'` adds a pulsing inner glow while AI is still producing it (stops under reduced motion). Visual only — pair it with an AiBadge so the provenance is also text. |
children | ReactNode | — | Modal body content |
Design tokens
--cascivo-color-surface-overlay--cascivo-color-border--cascivo-radius-modal--cascivo-shadow-xl--cascivo-focus-ring--cascivo-dialog-body-gap
When to use
- Presenting focused content or a task that must interrupt the current flow
- Confirmations and forms that require the user to act before continuing
- Cases needing a modal backdrop, focus trap, and Escape-to-close from the native <dialog>
When not to use
- Anchored, non-modal content next to a trigger — use Popover
- A side panel or drawer for secondary content — use Sheet
- A destructive confirmation with a clear yes/no decision — use AlertDialog
How to build an accessible Modal in React →
Examples
Basic modal
<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm action">
<p>Are you sure?</p>
</Modal>Related components
- AlertDialog — Use AlertDialog for a focused confirm/cancel decision, especially destructive ones
- Sheet — Use Sheet for an edge-anchored drawer rather than a centered dialog
- Popover — Use Popover for lightweight, non-modal content anchored to a trigger