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.

HTML
<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.

HTML
<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.

HTML
<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.

HTML
<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 .modal to a native dialog and connect its visible heading with aria-labelledby. Open it with showModal() and close it with close() 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.

TokenDefaultPurposeScope / state
--modal-widthmin(32rem, calc(100vw - var(--spacer-4)))Dialog width, constrained by the viewport..modal
--modal-max-heightcalc(100dvh - var(--spacer-4))Height limit shared by the dialog and content shell..modal
--modal-bg-colorvar(--bg-surface)Background color..modal
--modal-colorvar(--text-color)Text and icon color..modal
--modal-border-widthvar(--border-width)Border thickness..modal
--modal-border-colorvar(--border-color)Border color..modal
--modal-border-radiusvar(--border-radius)Corner radius..modal
--modal-header-border-colorvar(--modal-border-color)Divider color below the header..modal
--modal-footer-border-colorvar(--modal-border-color)Divider color above the footer..modal
--modal-box-shadowvar(--shadow-lg)Outer shadow..modal
--modal-header-paddingvar(--spacer-3)Header inner spacing..modal
--modal-body-paddingvar(--spacer-3)Scrollable body inner spacing..modal
--modal-footer-paddingvar(--spacer-3)Footer inner spacing..modal
--modal-backdrop-bg-colorrgb(from var(--gray-800) r g b / 0.7)Native dialog backdrop color..modal