Anatomy
- Header: The top section of the modal containing the title and close button (×) elements.
- Title: Text displayed in the header area that describes the context and purpose of the modal.
- Close Button: Button positioned at the top-right corner of the modal header for dismissing the modal.
- Body: The main content area that displays information, forms, or other interactive elements.
- Footer: The bottom section that contains action buttons and controls. Typically aligned to the right with the primary action positioned at the far right, but with multiple layouts.
- Actions: Interactive buttons in the footer area.
Usage Guidelines
When to use this component
- To build a new floating layer over the current page to show information or collect user input when you need users to interact with the application without having to navigate to a new page and disrupt their workflow.
- To confirm decisions, destructive or important actions before proceeding, ensuring users make deliberate decisions.
- Display forms that require focused user input, especially when the form is short to medium in complexity.
- Present important information that requires immediate user attention and acknowledgment.
- Create isolated workflows that need completion before returning to the main interface.
When not to use this component
- For success messages, warnings, or informational content that doesn't require immediate action. Use Toast or Banner components instead.
- As a substitute for proper page navigation or to display substantial amounts of content.
- For promotional or marketing modals that appear without user request.
- For multi-step processes or complex forms that require significant time to complete.
Best Practices
Open modal dialogs only in response to explicit user actions (button clicks, menu selections)
Don't display modals automatically without user request or action, i.e., for marketing purposes
Use clear, concise titles that explain the modal's purpose and context
Don't use modals without descriptive titles or headers
Align action buttons to the right with primary actions positioned at the far right
Don’t overcrowd the footer with too many actions. Include max of 2 actions to provide a clear hierarchy
Consider providing a “Cancel” button for modal dialogs that require action from the user
Don’t provide custom close button in the footer for passive modal dialogs
Seek confirmation before closing modals if users will lose progress
Don't nest modals within other modals if the situation requires a sequence of decisions
Don't include navigation elements or complex page structures within modals. A dialog should be used within a single context
General Component Behaviors
Modals create a focused interaction layer that temporarily takes precedence over the main page content. When activated, the modal captures user attention through visual prominence and interaction constraints.
- The modal automatically manages focus by moving keyboard navigation to the dialog elements and trapping focus within the modal boundaries.
- Users cannot interact with background content while the modal is active.
- Background content becomes visually subdued through an overlay effect, creating clear visual separation between the modal and underlying page elements.
Content height
The modal automatically adjusts its height based on content, implementing scroll behavior within the content area when necessary to prevent the modal from exceeding viewport boundaries. Modal dialogs include safespace area between the modal and viewport equal to Space L.
Positioning
Modal dialogs are always displayed in the center of the screen with a visible background that covers the content behind them.
Dismissing
Modal dialogs provide multiple ways to exit them:
- X button in top right corner
- Mouse click outside of the modal dialog
- Browser back button
- Escape key using keyboard
- Custom close button (Optional)
Responsive Behavior
Modal dialogs maintain consistent behavior across all device sizes while adapting their presentation for optimal usability. The modal always remains centered within the viewport with appropriate spacing.
On larger screens, modals display with fixed maximum widths and generous spacing around the dialog. On smaller devices, modals expand to use available screen real estate while maintaining minimum spacing for usability.
Sizes
Medium
The default modal size suitable for most use cases including confirmation dialogs, simple forms, and moderate amounts of content. Width is optimized for readability without overwhelming the interface.
Large
Expanded modal size appropriate for complex forms, data tables, or substantial content that benefits from additional space. Should not be used for simple confirmation dialogs.
Extra large
Maximum modal size for content that requires significant screen real estate, such as detailed forms, data visualization, or multi-column layouts.
Content Guidelines
- Modal titles should be concise and descriptive, clearly communicating the modal's purpose in 1-7 words. Use sentence case and avoid unnecessary articles.
- Action button labels should use clear, action-oriented language that describes exactly what will happen when clicked. Primary actions use strong verbs, while secondary actions use neutral terms like "Cancel" or "Close".
- Body content should be scannable and focused, presenting only information directly relevant to the modal's purpose. Avoid overwhelming users with excessive text or complex layouts.
- For confirmation modals, clearly state what action will be taken and any consequences. Use plain language and avoid technical jargon.
For further information, see the Content Styleguide.
Known Gaps
- Possible component improvements:
- To consider the possibility of having multi-step processes on them
- Detailed Accessibility Guidelines.