Skip to content

Overlay

C-08 · Components · Overlays

All elements · Overlay on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Overlay.

Overlay

C-08WCAG 2.2 AA · Passed #401

Every large dismissible surface: modal, drawer, inline panel, full page. A native <dialog> supplies the scrim and focus trap. The header carries the chrome tokens, so it goes navy.

Axis Values
data-presentation modal (default) · drawer · panel · fullscreen
data-size · data-placement sm · md · lg · xl / right (default) · left · bottom (drawer)
__header · __title · __body · __footer · __resize slots; body accepts data-padding="none"
Open real dialogs
Inline panel presentation
Invoice INV-2026-0412
Panels use the same header, body and footer as a modal but sit inline in the page flow.
Edit customer
Filters
Share
A bottom sheet for mobile-first actions.
Case CS-2041 · Water damage claim
ClaimantjdJane Doe
StatusIn review
Opened14 Aug 2026
Amount£4,250.00
AssessorUnassigned
PriorityHigh

Guidance

When to use

  • Use a modal overlay for a focused task that must finish or be cancelled before returning, such as editing a customer.
  • Use a drawer (data-presentation="drawer") for filters, settings or details that relate to the page behind it.
  • Use a panel (data-presentation="panel") to show a record inline in a pane with the same header, body and footer.
  • Use a large or fullscreen overlay to open a whole record, with tabs, without losing the list behind it.

When to consider something else

  • If you only need a yes or no before a risky action, use a confirmation. See Confirmation.
  • If the content is small and tied to one control, use a popover. See Popover.
  • If the panel should stay open next to the work, such as in the editors, use a task pane. See TaskPane.
  • If several windows, stacking and snapping are needed, use the overlay system. See OverlaySystem.

Usability

Do
  • Give every overlay a title that names the task or record.
  • Put Cancel or Close on the left of the footer and the primary action on the right.
  • Pick the smallest size that fits the task; use sm for short forms.
  • Warn before closing an overlay with unsaved changes.
Don’t
  • Don't open an overlay from inside another modal overlay.
  • Don't open an overlay without a user action.
  • Don't hide the close button; every overlay must be closable.

Accessibility

Keyboard

Overlay keyboard
Keys Action
Tab or Shift+Tab Moves through the controls in the overlay; in a modal it stays inside the overlay.
Escape Closes a modal or drawer (native <dialog> behavior).
Enter or Space On the close button or a footer button, runs it.

Roles and names

  • Modal and drawer use a native <dialog> opened with showModal(), which makes the page behind inert.
  • The dialog needs a name: aria-labelledby pointing at .qf-overlay__title, or aria-label.
  • Header icon buttons (Close, Maximize, Snap left) need aria-label.
  • The panel presentation is not a dialog; give it a region landmark or heading so it can be found.

Focus

  • On open, focus moves into the dialog (the first focusable control, or an element with autofocus).
  • The modal traps focus until it closes.
  • On close, the binding must return focus to the control that opened it.
  • Clicking the scrim closes the modal; make sure that is safe or confirm unsaved changes first.

Other requirements

  • The __resize corner is pointer only (2.5.7); Maximize and size options must give a single-pointer and keyboard way to resize.
  • At 320 CSS px wide the overlay must fit without horizontal scroll (1.4.10); prefer the fullscreen or bottom drawer on small screens.
  • The scrim must not hide the focus ring of the focused control inside the dialog (2.4.11).
  • The header uses chrome tokens and is navy; header text and icons must still reach 4.5:1 and 3:1.

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Overlay test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (3 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- overlay --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Overlay package
Source css/classic/components/overlays.css
css/classic/composites/documents.css
css/classic/composites/office-shell.css
css/classic/composites/overlay-system.css
css/classic/composites/windows.css
Specimens also use Avatar · Box · Button · Card · Chip · Control · Field · Form · Icon · ObjectDisplay · Table · Tabs · Text · Toggle · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes