Modal
Focused content or actions in a modal dialog.
When to use
Use a modal dialog for a focused task or confirmation that blocks interaction with the page until it is completed or dismissed. Use a Popover for non-modal supporting content.
Default
Apply .modal to native dialog. The static preview needs no script; applications use the native dialog API.
<button class="btn btn-primary btn-solid" type="button" data-modal-target="#defaultModal">
Open modal
</button>
<dialog class="modal" id="defaultModal" aria-labelledby="defaultModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="defaultModalTitle">Modal title</h3>
<button
class="modal-close icon-btn icon-btn-text"
type="button"
data-modal-close
aria-label="Close modal">
×
</button>
</div>
<div class="modal-body">
<p class="mb-0">This is a native dialog styled as a modal.</p>
</div>
<div class="modal-footer">
<button class="btn btn-secondary btn-text" type="button" data-modal-close>
Cancel
</button>
<button class="btn btn-primary btn-solid" type="button">Confirm</button>
</div>
</div>
</dialog>Simple modal
Omit footer actions when unnecessary.
<dialog class="modal" id="simpleModal" aria-labelledby="simpleModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="simpleModalTitle">Simple modal</h3>
<button
class="modal-close icon-btn icon-btn-text"
type="button"
data-modal-close
aria-label="Close modal">
×
</button>
</div>
<div class="modal-body">
<p class="mb-0">This modal only contains a header and body.</p>
</div>
</div>
</dialog>Long content
Long modal bodies scroll within the viewport.
<dialog class="modal" id="longContentModal" aria-labelledby="longContentModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="longContentModalTitle">Release checklist</h3>
<button
class="modal-close icon-btn icon-btn-text"
type="button"
data-modal-close
aria-label="Close modal">
×
</button>
</div>
<div class="modal-body">
<p>
Review the release checklist before publishing the updated component library.
Confirm that the documented classes, design tokens and examples match the version
included in the package.
</p>
<p>
Check the installation instructions in a clean project. Compile the Sass entry
point, load the resulting stylesheet and verify that the required fonts and theme
settings are available.
</p>
<p>
Walk through the forms with a keyboard. Each control should have a visible label, a
clear focus indicator and feedback that explains how to correct an invalid value.
</p>
<p>
Review the layouts on narrow and wide screens. Long headings, translated labels and
validation messages should wrap without hiding content or pushing actions outside
the viewport.
</p>
<p>
Compare the light and dark themes. Status messages should explain their meaning in
text, and links and interactive controls should remain distinguishable from the
surrounding content.
</p>
<p class="mb-0">
Record any remaining issues with the affected component and steps to reproduce them.
Share the checklist with the release reviewer when the documentation and package
checks are complete.
</p>
</div>
<div class="modal-footer">
<button class="btn btn-secondary btn-text" type="button" data-modal-close>Close</button>
</div>
</div>
</dialog>Sizes
Use .modal-sm, .modal-lg or .modal-xl for width.
<dialog class="modal modal-sm" id="smallModal" aria-labelledby="smallModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="smallModalTitle">Small modal</h3>
<!-- Close button -->
</div>
<!-- Modal body -->
</div>
</dialog>
<dialog class="modal modal-lg" id="largeModal" aria-labelledby="largeModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="largeModalTitle">Large modal</h3>
<!-- Close button -->
</div>
<!-- Modal body -->
</div>
</dialog>
<dialog class="modal modal-xl" id="extraLargeModal" aria-labelledby="extraLargeModalTitle">
<div class="modal-content">
<div class="modal-header">
<h3 class="modal-title" id="extraLargeModalTitle">Extra large modal</h3>
<!-- Close button -->
</div>
<!-- Modal body -->
</div>
</dialog>Accessibility and behavior
- Apply
.modalto a nativedialogand connect its visible heading witharia-labelledby. Open it withshowModal()and close it withclose()in application code. - Choose a useful initial focus target, keep keyboard access inside the modal while open, and restore focus to the opener when closing. Provide a named close button and Escape dismissal.
- The displayed previews are static and hidden from assistive technology. The package supplies styles; consuming applications own triggers, form actions and any additional dismissal policy.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--modal-width | min(32rem, calc(100vw - var(--spacer-4))) | Dialog width, constrained by the viewport. | .modal |
--modal-max-height | calc(100dvh - var(--spacer-4)) | Height limit shared by the dialog and content shell. | .modal |
--modal-bg-color | var(--bg-surface) | Background color. | .modal |
--modal-color | var(--text-color) | Text and icon color. | .modal |
--modal-border-width | var(--border-width) | Border thickness. | .modal |
--modal-border-color | var(--border-color) | Border color. | .modal |
--modal-border-radius | var(--border-radius) | Corner radius. | .modal |
--modal-header-border-color | var(--modal-border-color) | Divider color below the header. | .modal |
--modal-footer-border-color | var(--modal-border-color) | Divider color above the footer. | .modal |
--modal-box-shadow | var(--shadow-lg) | Outer shadow. | .modal |
--modal-header-padding | var(--spacer-3) | Header inner spacing. | .modal |
--modal-body-padding | var(--spacer-3) | Scrollable body inner spacing. | .modal |
--modal-footer-padding | var(--spacer-3) | Footer inner spacing. | .modal |
--modal-backdrop-bg-color | rgb(from var(--gray-800) r g b / 0.7) | Native dialog backdrop color. | .modal |