Modal
Last Updated: September 2026Modals are intentionally disruptive and intrusive overlay containers that seek the users full attention. Modals are best suited for warnings, verifications, or content configuration that requires the users full attention.
Source CodeAnatomy
link- 1Modal Title
- 2Dismiss Button
- 3Content Slot
- 4Footer Actions
Variants
linkConfirm
Title, description, close, body, and footer actions.
Sizes
Content size: xs, sm, md (default), lg — or width/height scale objects.
Close only
Omit Title/Description when Close should float alone.
Controlled
Drive open state from the parent with open / onOpenChange.
Usage Guidelines
linkWhen to use
- •For confirmations, short forms, and blocking decisions.
- •When the user should finish or dismiss before returning to the page.
- •For focused tasks that don't need a full page or drawer.
When not to use
- •For long multi-step flows — use a page or Drawer.
- •For non-blocking contextual tips — use Popover or Tooltip.
- •For persistent page content — don't hide it in a modal.
State the decision in the title and make the primary action explicit.
Don't use vague titles or label destructive actions as OK.
Keep modal content focused on a single short task.
Don't pack an entire page of content into a modal.
Behaviors
linkOpen and close
- •Uncontrolled: Modal.Trigger opens Content.
- •Controlled: open + onOpenChange on Modal.
- •Modal.Close and Esc dismiss unless configured otherwise.
Slots
- •Title, Description, Close, and Actions must be children of Modal.Content.
- •Remaining children render in the scrollable body.
Content Guidelines
linkTitles & descriptions
- •Title names the task or decision.
- •Description adds consequence or context — keep it to one or two sentences.
Actions
- •Put the primary action last in Modal.Actions.
- •Use danger variants for irreversible confirms.
Accessibility
linkText & Labels
- •Provide Modal.Title so the dialog has an accessible name.
- •Description supplements the title for screen readers when present.
ARIA attributes
- •Focus moves into the modal when opened and returns on close.
- •Backdrop uses the Overlay primitive.
Keyboard Support
- •Esc → dismiss.
- •Tab → cycle focus within the modal.
WCAG Compliance Standards
FAQs
linkHow do I wire the trigger?
Use Modal.Trigger with render={<Button … />}. The trigger props are merged onto your Button.
Modal vs Drawer vs Popover?
Modal for blocking short tasks, Drawer for longer side panels, Popover for lightweight anchored content.
Where do Title and Actions go?
As children of Modal.Content. The Content component slots them into the header and footer automatically.