Modal

ReactProps

Github Storybook Markdown Copy for LLM

The Modal component provides a way to display content in a layer that sits above the rest of the page content. It's commonly used for confirmation dialogs, message boxes, and other content that should temporarily block interactions with the main view.

Import

import { Modal } from "@cfa/react-core";

Live Editor

Guidelines

When to use

• Modal is for a single decision or short task that blocks the page until it is complete.

Do

• Use Modal sparingly.
• Use Confirm + Cancel for reversible decisions. Use Destructive + Cancel for irreversible actions. Follow Button guidance for labels and confirmation steps.
• Include a close control. Allow Esc and backdrop dismiss only when backing out will not lose data or interrupt a required flow.
• In horizontal action rows, place Primary on the right and Cancel on the left in left-to-right layouts.

Avoid

• Using Modal for status or feedback. Use Toast, BannerMessage, or MessageBlock.
• Stacking Modals. For a next step or confirmation, change content in the same Modal. For longer flows use a full page or Drawer.
• Using Modal for an ancillary task in a side panel. Use Drawer.

Examples

Composition

Compose Modal.Title, Modal.Content, and Modal.Footer as direct children of Modal.Dialog:

• Modal.Title — dialog title and accessible name
• Modal.Content — centered body copy
• Modal.Footer — action buttons
• Modal.CloseButton — pre-styled cancel/dismiss button

Modal.Dialog applies layout padding and section spacing. Modal.Content styles the body region only. Do not nest Modal.Title or Modal.Footer inside Modal.Content.

Write the title as the decision and restate the action in the primary button.

Destructive confirmation

Use explicit button labels and the destructive button variant for irreversible actions.

Fullscreen acknowledgment

Use a fullscreen modal for a brief acknowledgment that needs the full viewport.

Controlled Modal

Control the open state from the parent component with isOpen and onOpenChange.

Dismissable Modal

Allow closing by clicking outside the modal or pressing ESC. When using Modal.Overlay, pass isDismissable to Overlay instead of Dialog.

Custom Overlay

Modal.Overlay is optional — use it only to customize the backdrop (for example, background color or className). For stacking conflicts, add isolation: isolate to your app wrapper instead of setting z-index on the overlay. When using a custom Overlay tree, pass isDismissable and isKeyboardDismissDisabled to Overlay, not Dialog.

Size

Prefer the size prop over custom width styles.

Custom Styling

Use CSS classes or inline styles only when the built-in size options are not enough.