Overlay

Description #

<vaadin-overlay> is a Web Component for creating overlays. The content of the overlay can be populated imperatively by using renderer callback function.

Rendering #

The renderer function provides root, owner, model arguments when applicable. Generate DOM content by using model object properties if needed, append it to the root element and control the state of the host element by accessing owner. Before generating new content, users are able to check if there is already content in root for reusing it.

<vaadin-overlay id="overlay"></vaadin-overlay>

const overlay = document.querySelector('#overlay');
overlay.renderer = function(root) {
 root.textContent = "Overlay content";
};

Renderer is called on the opening of the overlay and each time the related model is updated. DOM generated during the renderer call can be reused in the next renderer call and will be provided with the root argument. On first call it will be empty.

Styling #

The following Shadow DOM parts are available for styling:

Part name	Description
backdrop	Backdrop of the overlay
overlay	Container for position/sizing/alignment of the content
content	Content of the overlay

The following state attributes are available for styling:

Attribute	Description	Part
opening	Applied just after the overlay is attached to the DOM. You can apply a CSS @keyframe animation for this state.	:host
closing	Applied just before the overlay is detached from the DOM. You can apply a CSS @keyframe animation for this state.	:host

The following custom CSS properties are available for styling:

Custom CSS property	Description	Default value
--vaadin-overlay-viewport-bottom	Bottom offset of the visible viewport area	0 or detected offset

See Styling Components documentation.

Properties #

focusTrap #

Type: boolean

When true, opening the overlay moves focus to the first focusable child, or to the overlay part with tabindex if there are no focusable children.

hidden #

Type: boolean

When set to true, the overlay is hidden. This also closes the overlay immediately in case there is a closing animation in progress.

model #

Type: object | null | undefined

Object with properties that is passed to renderer function

modeless #

Type: boolean

When true the overlay won't disable the main content, showing it doesn't change the functionality of the user interface.

opened #

Type: boolean | null | undefined

When true, the overlay is visible and attached to body.

owner #

Type: HTMLElement | null

Owner element passed with renderer function

renderer #

Type: OverlayRenderer | null | undefined

Custom function for rendering the content of the overlay. Receives three arguments:

• root The root container DOM element. Append your content to it.
• owner The host element of the renderer function.
• model The object with the properties related with rendering.

See also: OverlayRenderer

restoreFocusNode #

Type: HTMLElement | undefined

Set to specify the element which should be focused on overlay close, if restoreFocusOnClose is set to true.

restoreFocusOnClose #

Type: boolean

Set to true to enable restoring of focus when overlay is closed.

withBackdrop #

Type: boolean

When true the overlay has backdrop on top of content when opened.

Methods #

bringToFront #

Type: () => void

Brings the overlay as visually the frontmost one.

close #

Type: (sourceEvent?: Event | null | undefined) => void

requestContentUpdate #

Type: () => void

Requests an update for the content of the overlay. While performing the update, it invokes the renderer passed in the renderer property.

It is not guaranteed that the update happens immediately (synchronously) after it is requested.

setBounds #

Type: (bounds: OverlayBounds, absolute?: boolean | undefined) => void

Updates the coordinates of the overlay.

Events #

opened-changed #

Type: OverlayOpenedChangedEvent

Fired when the opened property changes.

vaadin-overlay-close #

Type: CustomEvent

vaadin-overlay-close Fired when the opened overlay is about to be closed. Calling preventDefault() on the event cancels the closing.

vaadin-overlay-closed #

Type: CustomEvent

vaadin-overlay-closed Fired after the overlay is closed.

vaadin-overlay-closing #

Type: CustomEvent

vaadin-overlay-closing Fired when the overlay starts to close. Closing the overlay can be asynchronous depending on the animation.

vaadin-overlay-escape-press #

Type: CustomEvent

vaadin-overlay-escape-press Fired before the overlay is closed on Escape key press. Calling preventDefault() on the event cancels the closing.

vaadin-overlay-open #

Type: CustomEvent

vaadin-overlay-open Fired after the overlay is opened.

vaadin-overlay-outside-click #

Type: CustomEvent

vaadin-overlay-outside-click Fired before the overlay is closed on outside click. Calling preventDefault() on the event cancels the closing.

Types #

OverlayOpenedChangedEvent #

/**
 * Fired when the `opened` property changes.
 */
export type OverlayOpenedChangedEvent = CustomEvent<{ value: boolean }>;

OverlayRenderer #

export type OverlayRenderer = (root: HTMLElement, owner: HTMLElement, model?: object) => void;