presentation form · Structural containers and states
Scrim
A translucent dark layer that covers the page behind a modal surface, blocking interaction and visually separating the modal from the background content.
Decisive boundary
A scrim communicates modality visually and blocks background interaction. Do not use it for toasts, tooltips, or non-modal surfaces.
Definition and intent
What is a Scrim UI pattern?
Use the behavior, not the silhouette
A translucent dark layer that covers the page behind a modal surface, blocking interaction and visually separating the modal from the background content. The term is used here as a presentation form that describes placement or motion without deciding every semantic behavior. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Visually and functionally separate a modal surface from the rest of the page. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Scrim, the boundary is: A scrim communicates modality visually and blocks background interaction. Do not use it for toasts, tooltips, or non-modal surfaces.
Do not implement it as Tooltip hover styling, and non-modal popovers where background interaction must remain available. If those requirements describe the real task better, use the related pattern page or the full Structural containers and states comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Visually and functionally separate a modal surface from the rest of the page.
Define opening and closing
Appears automatically when a modal surface opens. Disappears when the modal closes; clicking the scrim itself may dismiss the modal when designed.
Specify access behavior
Does not receive focus; may capture click events that dismiss the associated modal. No direct keyboard role; Escape dismisses the modal, which removes the scrim.
Reject the near miss
Tooltip hover styling, and non-modal popovers where background interaction must remain available.
Behavior contract
What must survive the build
- trigger
- Appears automatically when a modal surface opens.
- dismissal
- Disappears when the modal closes; clicking the scrim itself may dismiss the modal when designed.
- modality
- Blocks interaction with content behind it; content is inert.
- focus
- Does not receive focus; may capture click events that dismiss the associated modal.
- keyboard
- No direct keyboard role; Escape dismisses the modal, which removes the scrim.
- interactive
- Usually non-interactive beyond optional click-to-dismiss behavior.
- persistence
- Remains for the duration of the modal presentation.
- placement
- Covers the entire viewport behind the modal surface.
- mobile
- Full-viewport coverage with a consistent opacity; do not trap scroll on the overlay when the modal content itself scrolls.
Failure modes
Common wrong builds
- Putting interactive content on the scrim itself.
- Using a scrim for non-modal surfaces.
- Failing to animate the scrim entrance and exit.
- Leaving the scrim visible when the modal is dismissed.
Observable checks
Verify the result
- The scrim blocks pointer events on the background.
- It covers the full viewport.
- A click on the scrim dismisses the modal when that behavior is documented.
- The scrim disappears when the modal closes.
- The opacity provides sufficient contrast to signal modality.
Coding-agent handoff
Implementation brief template
Pattern: Scrim Purpose: Visually and functionally separate a modal surface from the rest of the page. Trigger: Appears automatically when a modal surface opens. Dismissal behavior: Disappears when the modal closes; clicking the scrim itself may dismiss the modal when designed. Modality: Blocks interaction with content behind it; content is inert. Focus behavior: Does not receive focus; may capture click events that dismiss the associated modal. Keyboard behavior: No direct keyboard role; Escape dismisses the modal, which removes the scrim. Interactive content: Usually non-interactive beyond optional click-to-dismiss behavior. Placement: Covers the entire viewport behind the modal surface. Mobile behavior: Full-viewport coverage with a consistent opacity; do not trap scroll on the overlay when the modal content itself scrolls. Do not implement as: Tooltip hover styling, and non-modal popovers where background interaction must remain available. Acceptance checks: - The scrim blocks pointer events on the background. - It covers the full viewport. - A click on the scrim dismisses the modal when that behavior is documented. - The scrim disappears when the modal closes. - The opacity provides sufficient contrast to signal modality.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Scrim UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Scrim in web UI?
A translucent dark layer that covers the page behind a modal surface, blocking interaction and visually separating the modal from the background content. In this reference set it is a presentation form that describes placement or motion without deciding every semantic behavior.
When should I use a Scrim?
Visually and functionally separate a modal surface from the rest of the page. The decisive boundary to confirm is this: A scrim communicates modality visually and blocks background interaction. Do not use it for toasts, tooltips, or non-modal surfaces.
What keyboard and focus behavior does a Scrim need?
No direct keyboard role; Escape dismisses the modal, which removes the scrim. Does not receive focus; may capture click events that dismiss the associated modal. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Scrim behave on mobile?
Full-viewport coverage with a consistent opacity; do not trap scroll on the overlay when the modal content itself scrolls. Its modality is a separate requirement: Blocks interaction with content behind it; content is inert.
How do I verify a Scrim implementation?
Start with observable checks: The scrim blocks pointer events on the background. It covers the full viewport. A click on the scrim dismisses the modal when that behavior is documented. Then verify the remaining checks and compare the result with the linked source guidance.