---
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-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.

### 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

### 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.

### 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.

## 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>;
```

### 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>;
```