Overlay
The Overlay component provides styling for creating overlays, backdrops, and splash screens that cover the entire viewport. It’s commonly used with dialogs, modals, and loading screens to focus user attention and prevent interaction with underlying content.
Dependencies
Section titled “Dependencies”- Metro UI Core
- CSS Variables
Basic Overlay
Section titled “Basic Overlay”<!-- Basic overlay --><div class="overlay"></div>
<!-- Transparent overlay --><div class="overlay transparent"></div>
<!-- Global overlay (higher z-index) --><div class="overlay global-overlay"></div>
<!-- Splash screen --><div class="splashscreen"> <div class="spinner large"></div> <h2>Loading...</h2></div>
Creating Overlays Programmatically
Section titled “Creating Overlays Programmatically”Overlays can be created programmatically using JavaScript:
// Create a basic overlayconst overlay = $("<div>").addClass("overlay").appendTo("body");
// Create a splash screenconst splash = $("<div>").addClass("splashscreen").appendTo("body");splash.append($("<div>").addClass("spinner large"));splash.append($("<h2>").text("Loading..."));
// Remove overlay when donesetTimeout(() => { overlay.remove(); splash.remove();}, 3000);
Using with Dialogs
Section titled “Using with Dialogs”Overlays are often used with dialogs to create modal experiences:
<!-- Overlay for a modal dialog --><div class="overlay"></div><div class="dialog"> <div class="dialog-title">Modal Dialog</div> <div class="dialog-content"> This dialog appears above the overlay. </div> <div class="dialog-actions"> <button class="button js-dialog-close">Close</button> </div></div>
Styling with CSS Variables
Section titled “Styling with CSS Variables”The Overlay component can be styled using the following CSS variables:
Variable | Default (Light) | Dark Mode | Description |
---|---|---|---|
--overlay-color | rgba(255,255,255, .5) | rgba(0,0,0, .5) | Background color of the overlay |
--splash-color | rgba(255,255,255, 1) | rgba(0,0,0, 1) | Background color of the splash screen |
Example of Custom Styling
Section titled “Example of Custom Styling”/* Custom styling for overlays */.custom-overlay { --overlay-color: rgba(0, 123, 255, 0.3);}
/* Custom styling for splash screens */.custom-splash { --splash-color: rgba(33, 37, 41, 0.95);}
Available CSS Classes
Section titled “Available CSS Classes”Base Classes
Section titled “Base Classes”.overlay
- Base class for overlays that covers the entire viewport.splashscreen
- Full-screen splash screen for loading states
Modifier Classes
Section titled “Modifier Classes”.transparent
- Makes the overlay completely transparent while still blocking interactions.global-overlay
- Overlay with higher z-index for global use.global-dialog
- Dialog that appears above global overlays
Z-Index Hierarchy
Section titled “Z-Index Hierarchy”The Overlay component uses a specific z-index hierarchy to ensure proper stacking:
- Standard overlays (z-index: 1040)
- Global overlays (z-index: 2000)
- Global dialogs (z-index: 2001)
- Splash screens (z-index: 2050)
This hierarchy ensures that elements appear in the correct order when multiple overlays or dialogs are present.
Accessibility
Section titled “Accessibility”When using overlays, consider the following accessibility best practices:
- Ensure that modal dialogs trap focus within them when an overlay is active
- Provide a way to dismiss overlays using both mouse and keyboard
- Consider adding
aria-hidden="true"
to content behind the overlay - For splash screens, consider adding a screen reader announcement about loading status
Best Practices
Section titled “Best Practices”- Use overlays sparingly to avoid disrupting user flow
- Provide clear visual indication of what’s happening when an overlay is shown
- Always include a way to dismiss the overlay (close button, escape key, etc.)
- For loading overlays, consider adding a progress indicator or estimated time
- Use transparent overlays when you want to maintain visual context while preventing interaction