Overlay Overview

The overlay component creates a full-page overlay layer that sits on top of the main content. It's commonly used as a backdrop for modals, dialogs, and other overlaid content to focus user attention and prevent interaction with underlying elements.

When to Use

✅ Use overlay when:

  • Creating modal dialogs that require user focus
  • Building custom popups or lightboxes
  • Implementing loading states that block interaction
  • Creating photo galleries or media viewers
  • Building custom dropdown menus or megamenus

❌ Don't use overlay for:

  • Simple tooltips (use the tooltip component)
  • Inline notifications (use callout or snackbar)
  • Page-level loading indicators (consider a dedicated loading component)
Examples Basic Usage

The overlay is hidden by default. Set the open property to true to display it. Click the overlay to close it in this example.

Toggle Overlay

Overlay Content

Click anywhere to close

Custom Background Colors

Use CSS custom properties to customize the overlay's appearance. The --dds-overlay-background property controls the background color and opacity.

Dark Overlay Blue Overlay Light Overlay

Dark Overlay (rgba(0, 0, 0, 0.8))

Blue Overlay (rgba(0, 100, 200, 0.5))

Light Overlay (rgba(255, 255, 255, 0.9))

Custom Transitions

Control the overlay's animation with transition duration and timing function properties.

Slow Transition (2s) Bounce Effect

Slow Transition

Watch the 2-second fade animation

Bounce Effect

Custom cubic-bezier timing

Layered Overlays

Multiple overlays can be stacked using different z-index values. This is useful for nested modals or complex UI patterns.

Layer 1 (z-index: 1) Layer 2 (z-index: 10) Layer 3 (z-index: 100)

Layer 1 (Red)

Close

Layer 2 (Green)

Close

Layer 3 (Blue)

Close
Modal Dialog with Overlay

Combining overlay with other components to create a centered modal dialog.

Open Modal Dialog
Confirm Action Are you sure you want to proceed with this action? This operation cannot be undone. Cancel Confirm
Image Lightbox

Using overlay to create a simple image lightbox viewer.

View Image
Sample Click anywhere to close
Loading State

Creating a full-page loading indicator with overlay.

Simulate Loading (3s)
Loading... Please wait while we process your request
Custom Styling

The overlay component provides extensive customization options through CSS custom properties and parts.

CSS Custom Properties
Custom Styled Overlay

Gradient Overlay

Custom background with smooth transitions

Advanced Styling with CSS Parts

Use the CSS ::part() selector to apply advanced styling to the overlay element. Try editing the CSS below:

Select a presetBlur EffectRadial GradientStriped PatternGlass Morphism
Copy CSSFormat CSSResetLightDark
CSS Editor
Live Preview
Background ContentThis content will be overlaid

Overlay Content

Accessibility Requirements
  • Focus management: When overlay opens, focus should move to overlay content
  • Keyboard support: ESC key should close the overlay (implement in parent component)
  • ARIA attributes: The overlay automatically sets aria-hidden based on open state
  • Screen reader announcements: Announce when overlay opens/closes
Best Practices
  • Ensure sufficient color contrast for overlay content
  • Provide a clear way to close the overlay
  • Consider users with motion sensitivity when using transitions
  • Test with keyboard-only navigation
Importing 
import { DapDSOverlay } from 'dap-design-system'
Importing React 
import { DapDSOverlayReact } from 'dap-design-system/react'
Tree-Shakeable Imports

For optimal bundle sizes, use the tree-shakeable import syntax:

import { DapDSOverlay } from 'dap-design-system/components'
Attributes
PropertyTypeDefaultDescription
openbooleanfalseThe open state of the overlay.
Slots
NameDescription
(default)The content of the overlay.
Events
Event NameDescriptionType
dds-before-openFires before the overlay opens.CustomEvent
dds-openedFires after the overlay opens.CustomEvent
dds-before-closeFires before the overlay closes.CustomEvent
dds-closedFires after the overlay closes.CustomEvent
CSS Parts
Part NameDescription
baseThe overlay element
How to Use CSS Parts

You can style CSS parts using the ::part() pseudo-element selector:

/* Target a specific part */
.my-custom-dap-ds-overlay::part(base) {
  /* Your custom styles */
}

Example usage:

<dap-ds-overlay class="my-custom-dap-ds-overlay">
  Overlay
</dap-ds-overlay>

.my-custom-dap-ds-overlay::part(base) {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.

 CSS Custom Properties
Property NameDescription
--dds-overlay-z-indexControls the z-index of the overlay (default: 1)
--dds-overlay-backgroundControls the background of the overlay (default: var(--dds-black-10))
--dds-overlay-opacity-closedControls the opacity when overlay is closed (default: 0)
--dds-overlay-opacity-openControls the opacity when overlay is open (default: 1)
--dds-overlay-transition-durationControls the transition duration (default: var(--dds-transition-fast))
--dds-overlay-transition-timingControls the transition timing function (default: var(--dds-easing-ease-in-out))
How to Use CSS Custom Properties

CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:

Method 1: Inline styles (Quick customization)

<dap-ds-overlay
  style="--dds-overlay-z-index: value; --dds-overlay-background: value;">
  Overlay
</dap-ds-overlay>

Method 2: CSS classes (Reusable styles)

.my-custom-dap-ds-overlay {
  --dds-overlay-z-index: value;
  --dds-overlay-background: value;
  --dds-overlay-opacity-closed: value;
}

<dap-ds-overlay class="my-custom-dap-ds-overlay">
  Overlay
</dap-ds-overlay>

Method 3: Global theme customization

/* Apply to all instances */
dap-ds-overlay {
  --dds-overlay-z-index: value;
  --dds-overlay-background: value;
}

CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.