---
title: Dialog
description: Dialog
element: vaadin-dialog
---

## Description

`<vaadin-dialog>` is a Web Component for creating customized modal dialogs.

### Rendering

The content of the dialog can be populated by using the renderer callback function.

The renderer function provides `root`, `dialog` arguments.
Generate DOM content, append it to the `root` element and control the state
of the host element by accessing `dialog`. Before generating new content,
users are able to check if there is already content in `root` for reusing it.

```html
<vaadin-dialog id="dialog"></vaadin-dialog>
```
```js
const dialog = document.querySelector('#dialog');
dialog.renderer = function(root, dialog) {
  root.textContent = "Sample dialog";
};
```

Renderer is called on the opening of the dialog.
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`        | The overlay container
`content`        | The overlay content
`header`         | Element wrapping title and header content
`header-content` | Element wrapping the header content slot
`title`          | Element wrapping the title slot
`footer`         | Element wrapping the footer slot

The following state attributes are available for styling:

Attribute        | Description
-----------------|--------------------------------------------
`has-title`      | Set when the element has a title
`has-header`     | Set when the element has header renderer
`has-footer`     | Set when the element has footer renderer
`overflow`       | Set to `top`, `bottom`, none or both

The following custom CSS properties are available for styling:

Custom CSS property                      |
:----------------------------------------|
|`--vaadin-dialog-background`            |
|`--vaadin-dialog-border-color`          |
|`--vaadin-dialog-border-radius`         |
|`--vaadin-dialog-border-width`          |
|`--vaadin-dialog-max-width`             |
|`--vaadin-dialog-min-width`             |
|`--vaadin-dialog-padding`               |
|`--vaadin-dialog-shadow`                |
|`--vaadin-dialog-text-color`            |
|`--vaadin-dialog-title-color`           |
|`--vaadin-dialog-title-font-size`       |
|`--vaadin-dialog-title-font-weight`     |
|`--vaadin-dialog-title-line-height`     |
|`--vaadin-overlay-backdrop-background`  |

See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.

## Properties

### draggable

**Type:** `boolean`

Set to true to enable repositioning the dialog by clicking and dragging.

By default, only the overlay area can be used to drag the element. But,
a child element can be marked as a draggable area by adding a
"`draggable`" class to it, this will by default make all of its children draggable also.
If you want a child element to be draggable
but still have its children non-draggable (by default), mark it with
"`draggable-leaf-only`" class name.

### footerRenderer

**Type:** `DialogRenderer | null | undefined`

Custom function for rendering the dialog footer.
Receives two arguments:

- `root` The root container DOM element. Append your content to it.
- `dialog` The reference to the `<vaadin-dialog>` element.

When `footerRenderer` is set, the attribute `has-footer` is set on the dialog.

See also: [DialogRenderer](#dialogrenderer)

### headerRenderer

**Type:** `DialogRenderer | null | undefined`

Custom function for rendering the dialog header.
Receives two arguments:

- `root` The root container DOM element. Append your content to it.
- `dialog` The reference to the `<vaadin-dialog>` element.

If both `headerTitle` and `headerRenderer` are defined, the title
and the elements created by the renderer will be placed next to
each other, with the title coming first.

When `headerRenderer` is set, the attribute `has-header` is set on the dialog.

See also: [DialogRenderer](#dialogrenderer)

### headerTitle

**Type:** `string | null | undefined`

String used for rendering a dialog title.

If both `headerTitle` and `headerRenderer` are defined, the title
and the elements created by the renderer will be placed next to
each other, with the title coming first.

When `headerTitle` is set, the attribute `has-title` is set on the dialog.

### height

**Type:** `string | null`

Set the height of the dialog.
If a unitless number is provided, pixels are assumed.

### keepInViewport

**Type:** `boolean`

Set to true to prevent the dialog from moving outside the viewport bounds.
When enabled, all four edges of the dialog will remain visible, for example
when dragging the dialog or when the viewport is resized. Note that the
dialog will also adjust any programmatically configured size and position
so that it stays within the viewport.

### left

**Type:** `string`

Set the distance of the dialog from the left of the viewport.
If a unitless number is provided, pixels are assumed.

Note that the dialog uses an internal container that has some
additional spacing, which can be overridden by the theme.

### modeless

**Type:** `boolean`

Set to true to remove backdrop and allow click events on background elements.

### noCloseOnEsc

**Type:** `boolean`

Set to true to disable closing dialog on Escape press

### noCloseOnOutsideClick

**Type:** `boolean`

Set to true to disable closing dialog on outside click

### noFocusTrap

**Type:** `boolean`

Set to true to disable focus trapping.

### opened

**Type:** `boolean`

True if the dialog is visible and available for interaction.

### overlayRole

**Type:** `string`

The `role` attribute value to be set on the dialog. Defaults to "dialog".

### renderer

**Type:** `DialogRenderer | null | undefined`

Custom function for rendering the content of the dialog.
Receives two arguments:

- `root` The root container DOM element. Append your content to it.
- `dialog` The reference to the `<vaadin-dialog>` element.

See also: [DialogRenderer](#dialogrenderer)

### resizable

**Type:** `boolean`

Set to true to enable resizing the dialog by dragging the corners and edges.

### top

**Type:** `string`

Set the distance of the dialog from the top of the viewport.
If a unitless number is provided, pixels are assumed.

Note that the dialog uses an internal container that has some
additional spacing, which can be overridden by the theme.

### width

**Type:** `string | null`

Set the width of the dialog.
If a unitless number is provided, pixels are assumed.

## Methods

### requestContentUpdate

**Type:** `() => void`

Requests an update for the content of the dialog.
While performing the update, it invokes the renderer passed in the `renderer` property,
as well as `headerRender` and `footerRenderer` properties, if these are defined.

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

## Events

### closed

**Type:** [DialogClosedEvent](#dialogclosedevent)

Fired when the dialog is closed.

### drag-start

**Type:** [DialogDragStartEvent](#dialogdragstartevent)

Fired when the dialog drag is started.

### dragged

**Type:** [DialogDraggedEvent](#dialogdraggedevent)

Fired when the dialog drag is finished.

### opened-changed

**Type:** [DialogOpenedChangedEvent](#dialogopenedchangedevent)

Fired when the `opened` property changes.

### resize

**Type:** [DialogResizeEvent](#dialogresizeevent)

Fired when the dialog resize is finished.

### resize-start

**Type:** [DialogResizeStartEvent](#dialogresizestartevent)

Fired when the dialog resize is started.

## Types

### DialogClosedEvent

```ts
/**
 * Fired when the dialog is closed.
 */
export type DialogClosedEvent = CustomEvent;
```

### DialogDraggedEvent

```ts
/**
 * Fired when the dialog drag is finished.
 */
export type DialogDraggedEvent = CustomEvent<DialogPosition>;
```

### DialogDragStartEvent

```ts
/**
 * Fired when the dialog drag is started.
 */
export type DialogDragStartEvent = CustomEvent<DialogResizeDimensions>;
```

### DialogOpenedChangedEvent

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

### DialogPosition

```ts
export type DialogPosition = {
  top: string;
  left: string;
};
```

### DialogRenderer

```ts
export type DialogRenderer = (root: HTMLElement, dialog: Dialog) => void;
```

### DialogResizeDimensions

```ts
export type DialogResizeDimensions = {
  width: string;
  height: string;
  top: string;
  left: string;
};
```

### DialogResizeEvent

```ts
/**
 * Fired when the dialog resize is finished.
 */
export type DialogResizeEvent = CustomEvent<DialogResizeDimensions>;
```

### DialogResizeStartEvent

```ts
/**
 * Fired when the dialog resize is started.
 */
export type DialogResizeStartEvent = CustomEvent<DialogResizeDimensions>;
```