Overview
TheMtModal component creates an accessible modal dialog that appears above the main content with a backdrop. It supports various sizes, customizable headers and footers, and automatic focus management with keyboard navigation.
Import
Props
The title displayed in the modal header.
An optional subtitle displayed below the title in the modal header.
The width of the modal:
s: 27.5rem (440px)m: 45rem (720px)l: 64rem (1024px)xl: 90rem (1440px)full: 100% of viewport width
When true, removes padding from the modal content area. Useful for full-width content like tables or images.
When true, hides the entire modal header including title and close button.
Usage
Basic Modal
Large Modal with Custom Header
Full-Width Content (Inset)
Programmatic Control
Slots
The main content area of the modal.
Content displayed on the left side of the header before the title.
Content displayed immediately after the title.
Content displayed on the right side of the header before the close button.
The footer area, typically used for action buttons.
Sub-Components
MtModalRoot
The root wrapper component that provides context and renders the backdrop. Props:isOpen(boolean): Controls the modal’s open/close stateclosable(boolean, default: true): Whether the modal can be closed by clicking the backdrop or pressing Escape
change: Emitted when the modal state changes, passes the new state as argument
MtModalTrigger
A wrapper component that opens the modal when clicked. Props:as(Component): The component to render (e.g., MtButton)
MtModalClose
A wrapper component that closes the modal when clicked. Props:as(Component): The component to render (e.g., MtButton)
MtModalAction
A wrapper component that provides a close function to the click event handler. Props:as(Component): The component to render
click: Emitted when clicked, passes a closeModal function as argument
Events
The modal state is managed through theMtModalRoot component via the isOpen prop and change event.
Accessibility Features
- Focus Management: Automatically traps focus within the modal when open using
focus-trap - Keyboard Navigation:
- Press
Escapeto close the modal (when closable) - Tab navigation is confined to modal content
- Press
- ARIA Attributes:
role="dialog"on modal containeraria-modal="true"indicates modal behavioraria-labelledbylinks to the modal title for screen readers
- Teleport: Modal is rendered at the document body level to avoid z-index issues
- Backdrop: Click outside to close (when closable)
Additional Features
Scroll Shadows
The modal automatically displays subtle shadows at the top or bottom of the content area when scrollable content exists, providing a visual indicator that more content is available.Animations
Smooth enter/exit animations with reduced motion support:- Fade and scale effects on open/close
- Respects
prefers-reduced-motionuser preference
Stacking Warning
The component logs a warning when multiple modals are stacked, as this is not recommended for UX reasons.Best Practices
- Use appropriate widths: Choose a width that fits your content without being too large or cramped
- Provide clear actions: Always include clear primary and secondary actions in the footer
- Make it closable: Allow users to close modals unless performing a critical operation
- Avoid nesting: Don’t stack multiple modals on top of each other
- Use descriptive titles: Provide clear, concise titles that explain the modal’s purpose
- Consider mobile: Test modals on smaller screens to ensure they remain usable