Navigation Back to home

Overlay

A layout overlay for dialogs, confirmations and temporary detail views with programmatic open and close control.

Import
the javascript logo
import { Overlay } from "@schukai/monster/source/components/layout/overlay.mjs";
Source
the git logo
Package
the npm logo
Since
1.0.0
Overlay for review and interrupt flows

A page action opens the overlay, while the component keeps the lifecycle on the documented methods and events.

State: closed
Order confirmation

Use the overlay for short-lived confirmation, review, and interruption states that should not replace the current page.

Introduction

The Monster Overlay is a layout container for temporary surfaces such as confirmations, review dialogs, detail views and lightweight modal workflows. Use it when content should appear above the current page without leaving the surrounding context.

When to use Overlay

  • Use it for short, focused tasks: Confirm destructive actions, inspect details or show a compact secondary workflow.
  • Use it when open and close must be controllable: The component exposes documented methods and lifecycle events for programmatic usage.
  • Use it when the rest of the page should remain in place: Overlays work well for temporary interruption without route changes.
  • Do not use it for long-form page content: If the user needs navigation, deep scrolling or multiple persistent panels, a page or panel layout is usually the better choice.

Key Features

  • Programmatic open and close: Control the overlay through open(), close() and toggle().
  • Lifecycle events: React to monster-overlay-before-open, monster-overlay-open, monster-overlay-before-close and monster-overlay-closed.
  • Configurable entry points: Enable or disable the built-in open button and escape-key support through documented features.
  • Layout-friendly styling: The component integrates with Monster layout tokens instead of relying on ad-hoc modal CSS.

Typical mistakes

Keep overlay content focused. If the content starts behaving like a full page, the interaction cost rises quickly. Avoid hardcoded overlay colors or custom z-index stacks when the standard overlay styling already communicates the layer correctly.

Overlay Simple

This example uses the public open() and toggle() methods together with documented overlay events. It is the safer pattern when the launch action lives outside the overlay itself.

Checkout Review Overlay

Open the overlay from an explicit page action and keep state changes visible through documented methods and events.

Overlay state: closed

Order Summary

Confirm the final numbers before you submit the order or switch back to the product view.

  • 3 items ready for shipping
  • Express handling enabled
  • Invoice total: 124.00 EUR

Javascript

import "@schukai/monster/source/components/layout/overlay.mjs";

const overlay = document.getElementById("overlay-simple-demo");
const log = document.getElementById("overlay-simple-log");

const setState = (state) => {
	log.textContent = `Overlay state: ${state}`;
};

document.getElementById("overlay-simple-open")?.addEventListener("click", () => {
	overlay?.open();
});

document
	.getElementById("overlay-simple-toggle")
	?.addEventListener("click", () => {
		overlay?.toggle();
	});

overlay?.addEventListener("monster-overlay-before-open", () => {
	setState("opening");
});

overlay?.addEventListener("monster-overlay-open", () => {
	setState("open");
});

overlay?.addEventListener("monster-overlay-before-close", () => {
	setState("closing");
});

overlay?.addEventListener("monster-overlay-closed", () => {
	setState("closed");
});<script type="module">import "./script.mjs";</script>

HTML

<section style="display:grid;gap:var(--monster-space-5);container-type:inline-size;">
  <div
    style="display:grid;gap:var(--monster-space-4);padding:var(--monster-space-5);background:var(--monster-bg-color-secondary-2);color:var(--monster-color-secondary-2);border:1px solid var(--monster-color-border-secondary-2);"
  >
    <div style="display:grid;gap:var(--monster-space-2);">
      <strong>Checkout Review Overlay</strong>
      <p style="margin:0;">
        Open the overlay from an explicit page action and keep state changes visible
        through documented methods and events.
      </p>
    </div>
    <div style="display:flex;gap:var(--monster-space-3);flex-wrap:wrap;">
      <button id="overlay-simple-open" type="button">Open review overlay</button>
      <button id="overlay-simple-toggle" type="button">Toggle state</button>
    </div>
    <p id="overlay-simple-log" style="margin:0;">Overlay state: closed</p>
  </div>

  <monster-overlay id="overlay-simple-demo">
    <section
      style="min-block-size:100%;display:grid;place-items:center;padding:var(--monster-space-7) var(--monster-space-5);"
    >
      <div
        style="display:grid;gap:var(--monster-space-4);inline-size:min(34rem,100%);padding:var(--monster-space-6);background:var(--monster-bg-color-primary-1);color:var(--monster-color-primary-1);border:1px solid var(--monster-color-border-primary-2);"
      >
        <div style="display:grid;gap:var(--monster-space-2);">
          <strong>Order Summary</strong>
          <p style="margin:0;">
            Confirm the final numbers before you submit the order or switch back to
            the product view.
          </p>
        </div>
        <ul style="display:grid;gap:var(--monster-space-2);margin:0;padding-left:1.25rem;">
          <li>3 items ready for shipping</li>
          <li>Express handling enabled</li>
          <li>Invoice total: 124.00 EUR</li>
        </ul>
      </div>
    </section>
  </monster-overlay>
</section>

Stylesheet

/** no additional stylesheet is defined **/
Open in playground

Programmatic Overlay Control

This variant keeps the trigger outside the component and drives the overlay through open() and close(). That is the better fit for approval flows, notifications, or validation gates.

Programmatic announcement overlay

Use explicit methods when the opening flow depends on validation, asynchronous data, or a step outside the overlay content itself.

Scheduled maintenance

Payments are paused for 15 minutes while the fulfillment queue is re-synced. Existing drafts stay untouched.

Current flow: waiting for operator decision

Javascript

import "@schukai/monster/source/components/layout/overlay.mjs";

const overlay = document.getElementById("overlay-programmatic-demo");
const status = document.getElementById("overlay-programmatic-status");

document
	.getElementById("overlay-programmatic-open")
	?.addEventListener("click", () => {
		status.textContent = "Current flow: maintenance overlay requested";
		overlay?.open();
	});

document
	.getElementById("overlay-programmatic-close")
	?.addEventListener("click", () => {
		overlay?.close();
	});

overlay?.addEventListener("monster-overlay-open", () => {
	status.textContent = "Current flow: overlay is visible";
});

overlay?.addEventListener("monster-overlay-closed", () => {
	status.textContent = "Current flow: overlay is hidden";
});<script type="module">import "./script.mjs";</script>

HTML

<section style="display:grid;gap:var(--monster-space-5);">
  <div
    style="display:grid;gap:var(--monster-space-4);padding:var(--monster-space-5);background:var(--monster-bg-color-primary-2);color:var(--monster-color-primary-2);border:1px solid var(--monster-color-border-primary-2);"
  >
    <div style="display:grid;gap:var(--monster-space-2);">
      <strong>Programmatic announcement overlay</strong>
      <p style="margin:0;">
        Use explicit methods when the opening flow depends on validation,
        asynchronous data, or a step outside the overlay content itself.
      </p>
    </div>
    <div style="display:flex;gap:var(--monster-space-3);flex-wrap:wrap;">
      <button id="overlay-programmatic-open" type="button">Open announcement</button>
      <button id="overlay-programmatic-close" type="button">Close from page</button>
    </div>
  </div>

  <monster-overlay id="overlay-programmatic-demo">
    <section
      style="min-block-size:100%;display:grid;place-items:center;padding:var(--monster-space-7) var(--monster-space-5);"
    >
      <div
        style="display:grid;gap:var(--monster-space-4);inline-size:min(32rem,100%);padding:var(--monster-space-6);background:var(--monster-bg-color-secondary-1);color:var(--monster-color-secondary-1);border:1px solid var(--monster-color-border-secondary-2);"
      >
        <strong>Scheduled maintenance</strong>
        <p style="margin:0;">
          Payments are paused for 15 minutes while the fulfillment queue is
          re-synced. Existing drafts stay untouched.
        </p>
        <p id="overlay-programmatic-status" style="margin:0;">
          Current flow: waiting for operator decision
        </p>
      </div>
    </section>
  </monster-overlay>
</section>

Stylesheet

/** no additional stylesheet is defined **/
Open in playground

Component Design

This component uses the Shadow DOM to encapsulate its internal structure and styling. By leveraging a shadow root, the component's internal elements are isolated from the rest of the DOM, ensuring that external styles or scripts do not unintentionally affect its layout or behavior.

Shadow DOM and Accessibility

Because the component is encapsulated within a shadow root, direct access to its internal elements is restricted. This means developers cannot manipulate or style these elements from outside the component. The Shadow DOM helps maintain consistency in design and behavior by preventing external interference.

Customizing Through Exported Parts

Although the Shadow DOM restricts direct access to internal structures, customization is still possible through exported parts. Specific parts of the component are explicitly marked for export, making them accessible for styling via CSS. This allows you to tailor the component’s appearance without compromising its encapsulation.

Available Part Attributes

  • control: This part represents the entire control section of the slider, including navigation buttons and thumbnails. Use it to style the layout and background of the control panel.

The example below shows how to target and customize these parts using CSS part attributes:


monster-component::part(control) {
    background-color: #f0f0f0;
    padding: 10px;
}

Explanation of the Example

  • monster-slider::part(control): Applies styling to the entire control panel, adding a light background color and some padding for spacing.

Accessibility

Accessibility is a key consideration in the design of this component. By following best practices for web accessibility, the component ensures that users of all abilities can interact with it effectively. This includes support for keyboard navigation, screen readers, and other assistive technologies to provide an inclusive user experience.

HTML Structure

<monster-overlay></monster-overlay>

JavaScript Initialization

const element = document.createElement('monster-overlay');
document.body.appendChild(element);

Exported

Overlay

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option
Type
Default
Description
templates
object
Template definitions
templates.main
string
undefined
Main template
overlay
string
undefined
Overlay definitions
overlay.content
string
undefined
Content template
overlay.class
string
undefined
Class name
classes.name
string
undefined
Name
classes
object
Class definitions
classes.body
string
hidden
Class name for the body
classes.overlay
string
hide-empty
Class name for the overlay
features
object
Feature definitions
features.escapeKey
boolean
true
If true the overlay can be closed with the escape key
features.openButton
boolean
false
If true the overlay can be opened with a button

  • since
  • deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

  • data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
  • data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Behavioral methods

close()
Returns
  • {Overlay}
open()
Returns
  • {Overlay}
Events
  • monster-overlay-before-open
  • monster-overlay-open
  • monster-overlay-before-close
  • monster-overlay-closed
toggle()
Returns
  • {Overlay}

Static methods

[instanceSymbol]()
Returns
  • {symbol}
This method is called by the instanceof operator.
getCSSStyleSheet()
Returns
  • {CSSStyleSheet[]}
getTag()
Returns
  • {string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()
Returns
  • {Overlay}
connectedCallback()

Events

The component emits the following events:

  • monster-overlay-before-open
  • monster-overlay-open
  • monster-overlay-before-close
  • monster-overlay-closed
  • monster-overlay-before-open
  • monster-overlay-open
  • monster-overlay-before-close
  • monster-overlay-closed

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.