Components, Overlays
Modal
A dialog that floats above the screen, with a header, a body and a footer fixed at the bottom.
Delete this conversation?
This deletes “Weekly report draft” and every message in it. You cannot undo this.
The modal is a dialog that floats above the screen. It has a header (title and close), a body, and a footer fixed at the bottom. The footer has one fill button. ConfirmDialog, RenameDialog and ChoiceDialog are built on top of it.
When to use
| size | Width | Use |
|---|---|---|
sm |
420 | Confirmations, short forms |
md (default) |
480 | The default |
lg |
560 | Forms |
xl |
720 | Pickers |
2xl |
880 | Usage and support shells |
3xl |
1120 | Settings shell |
height="tall" is fixed at 820px (settings, usage), and becomes full screen below 640px.
Anatomy
- Scrim:
overlay-scrim+ 8px background blur, outer margin 16. - Box:
cardsurface, 1pxborder, corner radius 12,shadow-lg. In dark, the surface takes the Stone tone. - Header: padding 16, 1px
borderbelow. The title is 16px, weight 600. Close is an IconButton md (icon 16). - Body: padding 16. When the content overflows, only the body scrolls. The description is 14px / 1.6
muted-foreground. - Footer: right aligned, 8 between buttons, padding 0 16 16. Buttons are BaseButton md.
Behavior
- It closes with Esc, a click on the backdrop, or the close button.
dismissible={false}turns off all three (re-authentication). - When it opens, focus moves inside and Tab cycles within it. When it closes, focus returns to the trigger.
- When modals are stacked, only the top one responds to Esc.
What you provide
title: required. A confirmation dialog uses a question (“Delete this conversation?”).description: what happens and whether it can be undone.footer: cancel (outline) on the left, the confirming action (fill or danger) on the right. The confirming label is the name of the action (“Delete”). Don’t write “OK” or “Confirm”.
Markup
<div class="BaseModal_backdrop">
<div class="BaseModal_modal" style="max-width: 420px" role="dialog" aria-modal="true" aria-labelledby="t" aria-describedby="d" tabindex="-1">
<header class="BaseModal_header">
<h2 id="t" class="BaseModal_title">Delete this conversation?</h2>
<button type="button" class="IconButton_btn IconButton_btn--ghost-muted IconButton_btn--md" aria-label="Close"><svg>…</svg></button>
</header>
<div class="BaseModal_body"><div id="d" class="BaseModal_description">…</div></div>
<div class="BaseModal_footer">…</div>
</div>
</div>
Set the width with an inline max-width. The header of a shell modal (settings) uses ModalShellHeader_header and ModalShellHeader_title.
Don’t
- Don’t create new flows that stack a modal on top of a modal.
- Don’t put more than three buttons in the footer.