Dialog

Modality
Draggable
Resizable
Closing
Layout and Scrolling
Best Practises
Related Components

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

Source code

dialog-basic-preview.tsimport { 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-vertical-layout>
            <vaadin-horizontal-layout theme="spacing" style="justify-content: flex-end">
              <vaadin-button>Cancel</vaadin-button>
              <vaadin-button theme="primary">Save changes</vaadin-button>
            </vaadin-horizontal-layout>
          </vaadin-vertical-layout>
        </div>
      </div>
    `;
    }
}
dialog-basic-preview.ts

Open in a
new tab

Source code

DialogBasic.javapackage com.vaadin.demo.component.dialog;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.dialog.Dialog;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.router.Route;

@Route("dialog-basic")
public class DialogBasic extends Div {

    public DialogBasic() {
        // tag::snippet[]
        Dialog dialog = new Dialog();
        dialog.getElement().setAttribute("aria-label", "Create new employee");

        VerticalLayout dialogLayout = createDialogLayout(dialog);
        dialog.add(dialogLayout);

        Button button = new Button("Show dialog", e -> dialog.open());
        add(dialog, button);
        // end::snippet[]
    }

    private static VerticalLayout createDialogLayout(Dialog dialog) {
        H2 headline = new H2("Create new employee");
        headline.getStyle().set("margin", "var(--lumo-space-m) 0 0 0")
                .set("font-size", "1.5em").set("font-weight", "bold");

        TextField firstNameField = new TextField("First name");
        TextField lastNameField = new TextField("Last name");
        VerticalLayout fieldLayout = new VerticalLayout(firstNameField,
                lastNameField);
        fieldLayout.setSpacing(false);
        fieldLayout.setPadding(false);
        fieldLayout.setAlignItems(FlexComponent.Alignment.STRETCH);

        Button cancelButton = new Button("Cancel", e -> dialog.close());
        Button saveButton = new Button("Save", e -> dialog.close());
        saveButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
        HorizontalLayout buttonLayout = new HorizontalLayout(cancelButton,
                saveButton);
        buttonLayout
                .setJustifyContentMode(FlexComponent.JustifyContentMode.END);

        VerticalLayout dialogLayout = new VerticalLayout(headline, fieldLayout,
                buttonLayout);
        dialogLayout.setPadding(false);
        dialogLayout.setAlignItems(FlexComponent.Alignment.STRETCH);
        dialogLayout.getStyle().set("width", "300px").set("max-width", "100%");

        return dialogLayout;
    }

}

Modality

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

Source code

JavaDialog dialog = new Dialog();
dialog.setModal(false);

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

Draggable

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

Source code

DialogDraggable.javapackage com.vaadin.demo.component.dialog;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.dialog.Dialog;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.component.textfield.TextArea;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.router.Route;

@Route("dialog-draggable")
public class DialogDraggable extends Div {

    public DialogDraggable() {
        Dialog dialog = new Dialog();
        dialog.getElement().setAttribute("aria-label", "Add note");

        VerticalLayout dialogLayout = createDialogLayout(dialog);
        dialog.add(dialogLayout);
        // tag::snippet1[]
        dialog.setModal(false);
        dialog.setDraggable(true);
        // end::snippet1[]

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

    private static VerticalLayout createDialogLayout(Dialog dialog) {
        H2 headline = new H2("Add note");
        headline.getStyle().set("margin", "0").set("font-size", "1.5em")
                .set("font-weight", "bold");
        HorizontalLayout header = new HorizontalLayout(headline);
        header.getElement().getClassList().add("draggable");
        header.setSpacing(false);
        header.getStyle()
                .set("border-bottom", "1px solid var(--lumo-contrast-20pct)")
                .set("cursor", "move");
        // Use negative margins to make draggable header stretch over full width,
        // covering the padding of the dialog
        header.getStyle()
                .set("padding", "var(--lumo-space-m) var(--lumo-space-l)")
                .set("margin",
                        "calc(var(--lumo-space-s) * -1) calc(var(--lumo-space-l) * -1) 0");

        TextField titleField = new TextField("Title");
        TextArea descriptionArea = new TextArea("Description");
        VerticalLayout fieldLayout = new VerticalLayout(titleField,
                descriptionArea);
        fieldLayout.setSpacing(false);
        fieldLayout.setPadding(false);
        fieldLayout.setAlignItems(FlexComponent.Alignment.STRETCH);

        Button cancelButton = new Button("Cancel", e -> dialog.close());
        Button saveButton = new Button("Add note", e -> dialog.close());
        saveButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
        HorizontalLayout buttonLayout = new HorizontalLayout(cancelButton,
                saveButton);
        buttonLayout
                .setJustifyContentMode(FlexComponent.JustifyContentMode.END);

        VerticalLayout dialogLayout = new VerticalLayout(header, fieldLayout,
                buttonLayout);
        dialogLayout.setPadding(false);
        dialogLayout.setAlignItems(FlexComponent.Alignment.STRETCH);
        dialogLayout.getStyle().set("width", "300px").set("max-width", "100%");

        return dialogLayout;
    }

}

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.

Resizable

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

Source code

DialogResizable.javapackage com.vaadin.demo.component.dialog;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.dialog.Dialog;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("dialog-resizable")
public class DialogResizable extends Div {

    public DialogResizable() {
        Dialog dialog = new Dialog();
        dialog.getElement().setAttribute("aria-label", "Employee list");

        VerticalLayout dialogLayout = createDialogLayout();
        dialog.add(dialogLayout);
        // tag::snippet[]
        dialog.setDraggable(true);
        dialog.setResizable(true);
        // end::snippet[]

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

    private static VerticalLayout createDialogLayout() {
        H2 headline = new H2("Employee list");
        headline.getStyle().set("margin", "var(--lumo-space-m) 0 0 0")
                .set("font-size", "1.5em").set("font-weight", "bold");

        Grid<Person> grid = new Grid<>(Person.class, false);
        grid.addColumn(Person::getFirstName).setHeader("First name");
        grid.addColumn(Person::getLastName).setHeader("Last name");
        grid.addColumn(Person::getEmail).setHeader("Email");
        grid.addColumn(Person::getProfession).setHeader("Profession");
        grid.addColumn(Person::getMembership).setHeader("Membership");

        List<Person> people = DataService.getPeople();
        grid.setItems(people);

        VerticalLayout dialogLayout = new VerticalLayout(headline, grid);
        dialogLayout.setPadding(false);
        dialogLayout.setAlignItems(FlexComponent.Alignment.STRETCH);
        dialogLayout.getStyle().set("min-width", "300px")
                .set("max-width", "100%").set("height", "100%");

        return dialogLayout;
    }

}

Closing

Modal Dialogs are closable in three ways:

Pressing the Esc key
Clicking outside the Dialog
Programmatically, for example through the click of a Button

Providing an explicit button for closing a Dialog is recommended.

Open in a
new tab

Source code

DialogClosing.javapackage com.vaadin.demo.component.dialog;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.dialog.Dialog;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

@Route("dialog-closing")
public class DialogClosing extends Div {

    public DialogClosing() {
        Dialog dialog = new Dialog();
        dialog.getElement()
                .setAttribute("aria-label", "System maintenance hint");

        VerticalLayout dialogLayout = createDialogLayout(dialog);
        dialog.add(dialogLayout);

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

    private static VerticalLayout createDialogLayout(Dialog dialog) {
        H2 headline = new H2("System maintenance");
        headline.getStyle().set("margin", "var(--lumo-space-m) 0")
                .set("font-size", "1.5em").set("font-weight", "bold");

        Paragraph paragraph = new Paragraph(
                "System maintenance will begin at 3 PM. It is schedule to conclude at 5PM. We apologise for any inconvenience.");

        // tag::snippet[]
        Button closeButton = new Button("Close");
        closeButton.addClickListener(e -> dialog.close());
        // end::snippet[]

        VerticalLayout dialogLayout = new VerticalLayout(headline, paragraph,
                closeButton);
        dialogLayout.setPadding(false);
        dialogLayout.setAlignItems(FlexComponent.Alignment.STRETCH);
        dialogLayout.getStyle().set("width", "300px").set("max-width", "100%");
        dialogLayout.setAlignSelf(FlexComponent.Alignment.END, closeButton);

        return dialogLayout;
    }

}

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

See Buttons in Dialogs.

Component	Usage recommendations
Confirm Dialog	Dialog for confirming user actions and decisions

Component

Usage recommendations

Confirm Dialog

Dialog for confirming user actions and decisions

1F2FC3C4-FD87-43C3-AF1B-59D7244B97AE

Docs

Docs

Dialog

Modality

Draggable

Resizable

Closing

Layout and Scrolling

Best Practises

Use Sparingly

Button Placement

Docs

Modality

Draggable

Resizable

Closing

Layout and Scrolling

Best Practises

Use Sparingly

Button Placement

Related Components