A modal is the most disruptive notification. It blocks the page until the user makes a decision, so use it only when the user must confirm or choose before going on.
Every “Open modal” button opens the real dialog: try ESC, a click on the dark overlay, Tab and the × to close it. Figma: E-Com Modal.
Choose size, label and content and the preview and its code update. Press Open modal to open the real one over this page.
Three situations that really need a decision. The line under the list tells you how the last modal was closed, because a modal must close in all of these ways: the ×, the ESC key and a click on the overlay.
No modal opened yet.
A modal is the most disruptive notification. It blocks the page until the user makes a decision, so use it only when the user must confirm or choose before going on.
It is shown over a dimmed page and it always closes with the ×, the ESC key and a click on the overlay. Feedback belongs in a Toast, status in context in an Inline notification. Not sure it is the right component? Start at the Notifications guide.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a modal. Specifications holds the values: tokens, sizes, measurements and requirements. Code shows how to open a modal from script and the CSS behind it.
Use a modal when the decision cannot wait. Use it to:
A modal stops the user. Feedback on something that has already happened does not need that: use a Toast.
The primary button says what will happen: “Delete”, not “OK”. The cancel button says how to back out.
| The message… | Use |
|---|---|
| needs a confirmation or a choice before the user can continue | Modal (this page) |
| confirms what happened, briefly | Toast |
| is status information in page context | Inline |
| concerns the whole page or system | Banner |
alt-label-sm, uppercase, in text-secondary.title-md, bold.body-md, text-secondary.surface-opacity-black-20, covers the page. The dimmed area in the figure.A modal has no status or emphasis. It varies in size (under Sizes) and in whether it carries a label.
The default: a title, a body and two buttons.
A small uppercase label above the title names the area the question belongs to, such as “Account” or “Cart”.
The modal comes in two sizes to choose between: Small and Large. Choose by the user’s task and need for work area. The breakpoint does not change that choice: it decides how the chosen size is adapted to the screen.
Use Small when the user is to make a quick, bounded decision or take in short information. The content is easy to overview and needs no extensive scrolling. Examples:
Use Large when the user needs more room to read, choose or enter information. Examples:
Rule of thumb: Small for short decisions. Large for tasks that need more work area.
The breakpoint controls how the chosen size is presented. The table sums up the three setups (the Figma breakpoint groups); exact values are under Sizes in Specifications. The figures below follow the Breakpoint toolbar.
| Desktop (769px+) | Tablet, sm (640–768px) | Mobile, xs (below 640px) | |
|---|---|---|---|
| Figma breakpoint | XLarge-Large-Medium | Small | XSmall (Large and Small only) |
| Small | 440px wide, centered | 440px wide (adapts to the available width), centered | Centered card, height by content, at least 16px side margin: max width 440px; 343px on a 375px viewport |
| Large | 705px wide, centered | 576px wide (adapts to the available width), centered | Fills the whole screen (375 × 100dvh): content on top, buttons pinned to the bottom |
| Height | By content, limited by the available screen height | By content, limited by the available screen height | Small: by content, limited by the screen height. Large: 100dvh |
| Padding | 24px | 24px | 16px |
| Type | Desktop sizes (label 14, title 20, body 17) | Mobile sizes (label 12, title 18, body 16) | Mobile sizes |
| Space above the buttons | 32px | 24px | 24px |
| Overlay | Dims the page | Dims the page | Small: dims the page. Large: covers it completely |
Small is a compact dialog. Large is a wider work area. The height follows the content and is limited by the available screen height.
The same usage rules apply, but the width adapts to the available area. Both sizes keep their side margins.
Choose Mobile in the Breakpoint toolbar to see Large as a full-screen view (a 375 × 560px screen here; the real one is 100dvh). Under Window the figure follows the width of your window.
The footer is not sticky: when the content is taller than the screen, the whole panel scrolls, buttons included. On a full-screen Large with short content the buttons sit at the bottom of the screen.
The label and the title sit on the left with the × on the right, top-aligned. The buttons are on one row at the bottom: Cancel on the left, and the Primary button fills the rest.
Desktop and tablet: the modal is centered in the window over a dimmed overlay. Mobile (below 640px): Small stays a centered card with side margins; Large is not centered, they fill the whole screen. See the table and the layout rules under Sizes.
Small 440px (on mobile too: max width 440px, never closer than 16px to the screen edges, so 343px on a 375px viewport). Large 705px on desktop, 576px on tablet, full screen on mobile.
A white panel with the highest shadow, over a 20% black overlay. Token names and values are under Design Tokens in Specifications.
A modal always closes in three ways: the ×, the ESC key and a click on the overlay. A click inside the panel does not close it.
When the modal opens, focus moves into the dialog and the page scroll is locked. Tab and Shift+Tab stay inside the dialog. On close, focus returns to the button that opened it.
Small is a centered card that keeps at least 16px to the screen edges and has the height of its content; if the content grows beyond the screen, the card gets a maximum height and scrolls inside. Large fills the screen: the content scrolls, the buttons stay pinned to the bottom, and the layout has to work in landscape and when the keyboard is open. The choice between them is under Sizes.
Buttons and the × take focus with a visible ring, on keyboard use only. All values are under Behavior in Specifications.
The overlay fades; the panel fades and moves 48px, up when it comes in (200ms, decelerate emphasized) and down when it leaves (150ms, accelerate): a modal closes faster than it opens. Try other values under Motion above, and see Motion in Specifications. With reduced motion there is no fade.
All requirements are listed under Accessibility Requirements in Specifications.
Tab and Shift+Tab move between the controls and stay inside the dialog. Esc closes it. Enter or Space activates the focused button.
The panel is role="dialog" with aria-modal="true" and aria-labelledby pointing at the title, so the dialog is announced with its name.