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 middle of the Elix render pipeline:
events → methods → setState ➞ 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 useOpenCloseMixin
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 untilcloseFinished
is true. This is designed to letOverlayMixin
interoperate cleanly with TransitionEffectMixin.
Provides the component with:
- internal.render method that applies overlay styling, primarily a
z-index
(see below). - 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/base/OverlayMixin.js";
class MyElement extends OverlayMixin(HTMLElement) {}
OverlayMixin
provides the core overlay behavior for Elix elements.
- OpenCloseMixin to provide a component with open/close semantics.
- PopupModalityMixin or DialogModalityMixin to intercept and respond to UI events.
- TransitionEffectMixin to handle asynchronous open/close CSS transition effects.
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
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.
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, DrawerWithGrip, Overlay, PlainAlertDialog, PlainDialog, PlainDrawer, PlainDrawerWithGrip, PlainOverlay, PlainPopup, PlainToast, Popup, and Toast.