Documentation versions (currently viewingVaadin 14)

You are viewing documentation for an older Vaadin version. View latest documentation


Dialog is a small window that can be used to present information and user interface elements in an overlay.

Open in a
new tab
import { css, html, LitElement } from 'lit-element';
import '@vaadin/vaadin-notification/vaadin-notification';
import '@vaadin/vaadin-button/vaadin-button';
import '@vaadin/vaadin-text-field/vaadin-text-field';
import '@vaadin/vaadin-ordered-layout/vaadin-horizontal-layout';
import '@vaadin/vaadin-ordered-layout/vaadin-vertical-layout';

export class Example extends LitElement {
    static get styles() {
        return css`
      :host {
        display: flex !important;
        justify-content: center;
        background-color: var(--lumo-shade-20pct);
        padding: var(--lumo-space-l);
        pointer-events: none;
        user-select: none;
        -webkit-user-select: none;

      .overlay {
        display: flex;
        justify-content: center;
        outline: none;
        -webkit-tap-highlight-color: transparent;
        background-color: var(--lumo-base-color);
        background-image: linear-gradient(var(--lumo-tint-5pct), var(--lumo-tint-5pct));
        border-radius: var(--lumo-border-radius-m);
        box-shadow: 0 0 0 1px var(--lumo-shade-5pct), var(--lumo-box-shadow-m);
        color: var(--lumo-body-text-color);
        font-family: var(--lumo-font-family);
        font-size: var(--lumo-font-size-m);
        font-weight: 400;
        line-height: var(--lumo-line-height-m);
        letter-spacing: 0;
        text-transform: none;
        -webkit-text-size-adjust: 100%;
        -webkit-font-smoothing: antialiased;

      .content {
        padding: var(--lumo-space-l);
        width: 300px;
        max-width: 100%;
    render() {
        return html`
      <div class="overlay">
        <div class="content">
          <vaadin-vertical-layout theme="spacing" style="align-items: stretch;">
            <h2 style="margin: var(--lumo-space-m) 0 0 0;">New employee</h2>
            <vaadin-vertical-layout style="align-items: stretch;">
              <vaadin-text-field label="First name"></vaadin-text-field>
              <vaadin-text-field label="Last name"></vaadin-text-field>
            <vaadin-horizontal-layout theme="spacing" style="justify-content: flex-end">
              <vaadin-button theme="primary">Save changes</vaadin-button>
Open in a
new tab
Dialog dialog = new Dialog();
dialog.getElement().setAttribute("aria-label", "Create new employee");

VerticalLayout dialogLayout = createDialogLayout(dialog);

Button button = new Button("Show dialog", e ->;
add(dialog, button);


A modal Dialog blocks the user from interacting with the rest of the user interface while the Dialog is open, as opposed to a non-modal Dialog which does not block interaction.

Dialogs are modal by default.

Use modal Dialogs for:

  • Displaying important information, like system errors

  • Requesting user input as part of a workflow, for example, an edit Dialog

  • Confirmation of irreversible actions, such as deleting data (Confirm Dialog is a convenient alternative for these use cases)

  • Breaking out sub-tasks into a separate user interface

Use non-modal Dialogs:

  • When the user needs access to the content below the Dialog

  • For less critical, optional, and/or support tasks

Dialog dialog = new Dialog();

Non-modal Dialogs should in most cases be draggable, so that the user can move them to access the user interface beneath.


Dialogs can be made draggable, enabling the user to move them around using a pointing device.

It is recommended to make non-modal Dialogs draggable so that the user can interact with content that might otherwise be obscured by the Dialog. For example, a Dialog for taking notes, or adding widgets to a dashboard using drag and drop, can offer a better experience by allowing the user to move the Dialog around.

Modal Dialogs don’t benefit from being draggable as their modality curtain (the dark overlay behind the dialog) obscures the underlying user interface.

Open in a
new tab


HorizontalLayout header = new HorizontalLayout(headline);

By default, the outer edges of a Dialog, as well as the space between its components, can be used to move the Dialog around.

Any component contained within a Dialog can be marked and used as a drag handle by applying the draggable class name to it. You can choose whether or not to make the component’s content draggable as well, or just the component itself.


A resizable Dialog allows the user to resize the Dialog by dragging from the edges of the Dialog with a pointing device. Dialogs are not resizable by default.

Dialogs containing dynamic content and/or a lot of information, such as complex forms or Grids, can benefit from being resizable as it offers the user some flexibility as to how much data is visible at once. It also gives the user control over which part of the underlying user interface is obscured.

Dialogs that contain very little or compact information do not need to be resizable.

Open in a
new tab


Modal Dialogs are closable in three ways:

  1. Pressing the Esc key

  2. Clicking outside the Dialog

  3. Programmatically, for example through the click of a Button

Providing an explicit button for closing a Dialog is recommended.

Open in a
new tab
Button closeButton = new Button("Close");
closeButton.addClickListener(e -> dialog.close());

Layout and Scrolling

Dialogs automatically become scrollable when their content overflows. Custom scrollable areas can be created using the Scroller component.

Best Practises

Use Sparingly

Dialogs are disruptive by nature and should be used sparingly. Do not use them to communicate nonessential information, such as success messages like “Logged in”, “Copied”, and so on. Instead, use Notifications when appropriate.

Button Placement

Component Usage recommendations

Confirm Dialog

Dialog for confirming user actions and decisions