OverlayMixin

Displays an opened element on top of other page elements

Overview

Purpose: make an opened element appear on top of other page elements, then hide or remove it when closed. This mixin is used to define the core overlay behavior for an Overlay; you can also use this mixin directly.

This mixin primarily works in the updates phase of the Elix render pipeline:

events → methods → setState → updates → render DOM → post-render

It also performs some additional work after updates have been rendered to the DOM.

Expects the component to provide:

  • closed property indicating whether the overlay is closed. You can use OpenCloseMixin to provide this property.
  • toggle method that is invoked to open or close the overlay. The mixin actually only requires this method if you will rely on it to automatically add an overlay to the DOM. (See below.) You can use OpenCloseMixin to define this method.
  • optional closeFinished property indicating whether the overlay has finished rendering its closed state. If defined, the overlay will not be rendered as closed until closeFinished is true. This is designed to let OverlayMixin interoperate cleanly with TransitionEffectMixin.

Provides the component with:

  • updates property for RenderUpdatesMixin that applies overlay styling, primarily a z-index (see below).
  • Appends the element to the DOM when opened, if it’s not already in the DOM. When later closed, the element will be removed from the DOM.
  • Remembers which element had the focus before the overlay was opened, and tries to restore the focus there when the overlay is closed.

Usage

import OverlayMixin from 'elix/src/OverlayMixin.js';
class MyElement extends OverlayMixin(HTMLElement) {}

OverlayMixin provides the core overlay behavior for Elix elements.

For a typical overlay element, consider using the Overlay base class, which defines template elements for a frame around the overlay content and an optional backdrop behind the overlay.

Example

Here's a dialog.

This paragraph has a z-index, but should appear behind the dialog. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse sed lorem scelerisque, blandit libero vitae, dapibus nisl. Sed turpis diam, placerat a feugiat sed, maximus at velit. Ut sit amet semper sapien. Donec vitae leo ex. Duis eget quam sed metus tempor lobortis eget feugiat elit. Cras varius, arcu ac commodo tincidunt, lectus dui convallis nunc, quis maximus nisl erat ac mi. Phasellus et velit diam.

Demo: A Dialog uses OverlayMixin to appear on top

Calculating a default z-index

If an overlay element has not been assigned a CSS z-index, OverlayMixin calculates a default z-index for the element that should be sufficient for it to appear above all currently-visible elements.

This calculation looks at all light DOM elements, so is theoretically expensive. That said, it only runs when an overlay is opening, and is only used if an overlay doesn't have a z-index already. In cases where performance is an issue, you can completely avoid this calculation by taking care to manually applying an appropriate z-index to an overlay.

API

Used by classes AlertDialog, Dialog, Drawer, Overlay, Popup, and Toast.