sp-underlay

NPM 1.6.0

View Storybook
Overview API Changelog

Overview

An <sp-underlay> provides a visual layer between overlay content and the rest of your application. It is commonly used with modal dialogs and other overlay elements to create a visual separation and prevent interaction with the background content while the overlay is active.

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/underlay

Import the side effectful registration of <sp-underlay> via:

import '@spectrum-web-components/underlay/sp-underlay.js';

When looking to leverage the Underlay base class as a type and/or for extension purposes, do so via:

import { Underlay } from '@spectrum-web-components/underlay';

Examples

Basic Usage

When using an <sp-underlay> with overlay content, place it as a sibling element before your overlay content.

<style>
    sp-underlay:not([open]) + sp-dialog {
        display: none;
    }
    sp-underlay + sp-dialog {
        position: fixed;
        top: 50%;
        left: 50%;
        transform: translate(-50%, -50%);
        z-index: 1;
        background: var(--spectrum-gray-100);
    }
</style>

<sp-button
    onclick="
        console.log(this.nextElementSibling);
        this.nextElementSibling.open = true;
    "
>
    Open dialog with underlay element
</sp-button>

<sp-underlay></sp-underlay>
<sp-dialog size="s">
    <h1 slot="heading">Hello, I'm an overlay!</h1>
    <p>Enjoy your day...</p>
    <sp-button
        slot="button"
        onclick="
            this.parentElement.previousElementSibling.open = false;
        "
    >
        Close
    </sp-button>
</sp-dialog>

Styling

To ensure proper layering of your overlay content with the underlay, use appropriate CSS:

<style>
    /* Hide overlay content when underlay is closed */
    sp-underlay:not([open]) + sp-dialog {
        display: none;
    }

    /* Position overlay content above the underlay */
    sp-underlay + sp-dialog {
        position: fixed;
        top: 50%;
        left: 50%;
        transform: translate(-50%, -50%);
        z-index: 1;
    }
</style>

Accessibility

The <sp-underlay> element helps create an accessible modal experience by:

  1. Providing visual separation between modal content and the rest of the page
  2. Supporting proper focus management when used with modal dialogs
  3. Helping communicate the modal state to assistive technologies

Attributes and Properties

Property Attribute Type Default Description open open boolean false

Events

Name Type Description close Event When the underlay is "clicked" and the consuming pattern should chose whether to close based on that interaction

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.6.0

1.5.0

Patch Changes

  • #5271 165a904 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies []:

    • @spectrum-web-components/base@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/underlay

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/underlay

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/underlay

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/underlay

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/underlay

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/underlay

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/underlay

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/underlay

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/underlay

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/underlay

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/underlay

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/underlay

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/underlay

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/underlay

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/underlay

0.41.0 (2024-02-13)

Bug Fixes

  • tray: only allow "click" events when they "pointerdown"ed on the Underlay (#4020) (4f9aa4a)

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/underlay

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/underlay

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/underlay

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/underlay

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/underlay

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/underlay

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/underlay

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/underlay

0.39.0 (2023-09-25)

Features

  • underlay: use core tokens (9c555ab)

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/underlay

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/underlay

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/underlay

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/underlay

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/underlay

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/underlay

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/underlay

0.30.0 (2023-05-03)

Bug Fixes

  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • add dialog, dialog-wrapped, and underlay elements (3df9050)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • underlay: update spectrum css input (edf1a4b)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use latest exports specification (a7ecf4b)

0.9.9 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.8 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.7 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.6 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.5 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/underlay

0.9.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.8.11 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.10 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.9 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.8 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.7 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.6 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.5 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.4 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.3 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.2 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/underlay

0.8.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.7.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.7.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.6.9 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.8 (2021-08-17)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.7 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.6 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.5 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/underlay

0.6.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.5.1 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.5.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • underlay: update spectrum css input (edf1a4b)

0.4.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • underlay: update spectrum css input (edf1a4b)

0.3.3 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/underlay

0.3.2 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.3.1 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.3.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.2.1 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/underlay

0.2.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.1.1 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/underlay

0.1.0 (2020-05-12)

Features

  • add dialog, dialog-wrapped, and underlay elements (3df9050)