---
title: Overlay
description: Overlay
element: vaadin-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.

```html
<vaadin-overlay id="overlay"></vaadin-overlay>
```
```js
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
----------|------------
`opening` | Applied just after the overlay is opened. You can apply a CSS animation for this state.
`closing` | Applied just before the overlay is closed. You can apply a CSS animation for this state.

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](https://vaadin.com/docs/latest/styling/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](#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](#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

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

### OverlayRenderer

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