Skip to content
AITroveRead. Build. Understand.
Reading list
Make this comfortable

CSS :modal: style the active modal state without faking modality

Last updated: 1 Oct 20265 min read
tutorial
BeginnerBy AITrove Editorial

The :modal pseudo-class matches an element in a modal state that excludes interaction outside it. A dialog opened with showModal() is a common case; a dialog merely opened with the open attribute is not equivalent. CSS cannot turn a normal panel into a modal dialog or implement the browser's focus and top-layer behavior.

When to use it

A document-rejection form opens as a native dialog when a reviewer chooses Reject. The base dialog rule gives its content a solid surface and bounded width; the modal state adds a distinct border. Keep the reason field's label, the Cancel and Confirm controls, and an obvious focus indicator in the markup. Test Tab and Shift+Tab, Escape or the configured close policy, a long error message, mobile viewport height, and forced colors. Do not style every :modal element globally: fullscreen content may also match and needs a different treatment. The border cannot communicate whether rejection has succeeded; wait for the server result and show that result in text. Avoid a transparent surface whose legibility depends on a blurred backdrop. If JavaScript never calls showModal(), the underlying page should still provide a route to complete or cancel the action rather than presenting a dead button.

css
.reject-dialog { box-sizing: border-box; max-inline-size: min(34rem, calc(100vw - 2rem)); max-block-size: calc(100dvh - 2rem); overflow: auto; color: #173441; background: #f7fafb; }
.reject-dialog:modal { border: 3px solid #325f73; }
.reject-dialog :focus-visible { outline: 3px solid #1b657f; outline-offset: 2px; }

Cost and verification

The selector itself is inexpensive. The important work is checking focus, close behavior, and form state under the real dialog interaction. A CSS border cannot enforce modality, trap focus, or restore focus after close. The browser's showModal() path supplies much of that behavior, but the application still has to handle cancellation and submit results correctly. The max-block-size avoids content disappearing beneath a short viewport; test the viewport-unit fallback in older browsers if those are supported. Scope the rule to this dialog so a fullscreen element is not accidentally styled as a rejection form.

Common Mistakes

  • Do not treat an open attribute as proof of modal behavior.
  • Do not use :modal as a page-wide theme selector.
  • Do not rely on border color to report the server result.

Connected lessons

css
reference
web
Storage details