Package com.vaadin.flow.component.dialog

Class Dialog

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.dialog.Dialog
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.HasComponents, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.component.HasTheme, HasThemeVariant<DialogVariant>, Serializable
@Tag("vaadin-dialog") @NpmPackage(value="@vaadin/dialog", version="25.0.0-alpha17") @JsModule("@vaadin/dialog/src/vaadin-dialog.js") @JsModule("./flow-component-renderer.js") public class Dialog extends com.vaadin.flow.component.Component implements com.vaadin.flow.component.HasComponents, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, HasThemeVariant<DialogVariant>
A Dialog is a small window that can be used to present information and user interface elements.

Dialogs can be made modal or non-modal. 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 can be made draggable and resizable. When draggable, the user is able 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. 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 automatically become scrollable when their content overflows. Custom scrollable areas can be created using the Scroller component.

Best Practices:
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.

Author:
Vaadin Ltd
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Dialog.ClosedEvent
    Event that is fired after the dialog's closing animation has finished.
    static class 
    Dialog.DialogCloseActionEvent
    `vaadin-dialog-close-action` is sent when the user clicks outside the dialog or presses the escape key.
    static class 
    Dialog.DialogDraggedEvent
    `dragged` event is sent when the user finishes dragging the dialog.
    static final class 
    Dialog.DialogFooter
    Class for adding and removing components to the footer part of a dialog.
    static final class 
    Dialog.DialogHeader
    Class for adding and removing components to the header part of a dialog.
    static class 
    Dialog.DialogResizeEvent
    `resize` event is sent when the user finishes resizing the dialog.
    static class 
    Dialog.OpenedChangeEvent
    Event that is fired when the dialog's opened state changes.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Dialog()
    Creates an empty dialog.
    Dialog(com.vaadin.flow.component.Component... components)
    Creates a dialog with given components inside.
    Dialog(String title)
    Creates a dialog with given title.
    Dialog(String title, com.vaadin.flow.component.Component... components)
    Creates a dialog with given title and components inside.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Collection<com.vaadin.flow.component.Component> components)
    Adds the given components into this dialog.
    com.vaadin.flow.shared.Registration
    addAttachListener(com.vaadin.flow.component.ComponentEventListener<com.vaadin.flow.component.AttachEvent> listener)
    com.vaadin.flow.shared.Registration
    addClosedListener(com.vaadin.flow.component.ComponentEventListener<Dialog.ClosedEvent> listener)
    Add a lister for when the dialog's closing animation has finished.
    void
    addComponentAtIndex(int index, com.vaadin.flow.component.Component component)
    Adds the given component into this dialog at the given index.
    com.vaadin.flow.shared.Registration
    addDetachListener(com.vaadin.flow.component.ComponentEventListener<com.vaadin.flow.component.DetachEvent> listener)
    com.vaadin.flow.shared.Registration
    addDialogCloseActionListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogCloseActionEvent> listener)
    Add a listener that controls whether the dialog should be closed or not.
    com.vaadin.flow.shared.Registration
    addDraggedListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogDraggedEvent> listener)
    Adds a listener that is called after the user finishes dragging the dialog.
    com.vaadin.flow.shared.Registration
    addOpenedChangeListener(com.vaadin.flow.component.ComponentEventListener<Dialog.OpenedChangeEvent> listener)
    Add a listener for when the dialog's opened state changes.
    com.vaadin.flow.shared.Registration
    addResizeListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogResizeEvent> listener)
    Adds a listener that is called after the user finishes resizing the dialog.
    void
    close()
    Closes the dialog.
    protected String
    getAriaLabel()
    Set the aria-label attribute for assistive technologies like screen readers.
    Dialog.DialogFooter
    getFooter()
    Gets the object from which components can be added or removed from the dialog footer area.
    Dialog.DialogHeader
    getHeader()
    Gets the object from which components can be added or removed from the dialog header area.
    String
    getHeaderTitle()
    Gets the title set for the dialog header.
    String
    getHeight()
     
    String
    getLeft()
    Gets the left position of the dialog.
    String
    getMaxHeight()
     
    String
    getMaxWidth()
     
    String
    getMinHeight()
     
    String
    getMinWidth()
     
    String
    getOverlayRole()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use getRole() instead
    String
    getRole()
    Gets the ARIA role for the dialog element, used by screen readers.
    com.vaadin.flow.dom.Style
    getStyle()
     
    String
    getTop()
    Gets the top position of the dialog.
    String
    getWidth()
     
    boolean
    isCloseOnEsc()
    Gets whether this dialog can be closed by hitting the esc-key or not.
    boolean
    isCloseOnOutsideClick()
    Gets whether this dialog can be closed by clicking outside of it or not.
    boolean
    isDraggable()
    Gets whether dialog is enabled to be dragged or not.
    boolean
    isModal()
    Gets whether component is set as modal or modeless dialog.
    boolean
    isOpened()
    Gets the open state from the dialog.
    boolean
    isResizable()
    Gets whether dialog is enabled to be resized or not.
    protected void
    onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
     
    void
    open()
    Opens the dialog.
    protected void
    setAriaLabel(String ariaLabel)
    Set the aria-label attribute for assistive technologies like screen readers.
    void
    setCloseOnEsc(boolean closeOnEsc)
    Sets whether this dialog can be closed by hitting the esc-key or not.
    void
    setCloseOnOutsideClick(boolean closeOnOutsideClick)
    Sets whether this dialog can be closed by clicking outside of it or not.
    void
    setDraggable(boolean draggable)
    Sets whether dialog is enabled to be dragged by the user or not.
    void
    setHeaderTitle(String title)
    Sets the title to be rendered on the dialog header.
    void
    setHeight(String value)
     
    void
    setLeft(String left)
    Sets the distance of the dialog from the left of its container.
    void
    setMaxHeight(String value)
     
    void
    setMaxWidth(String value)
     
    void
    setMinHeight(String value)
     
    void
    setMinWidth(String value)
     
    void
    setModal(boolean modal)
    Sets whether component will open modal or modeless dialog.
    void
    setOpened(boolean opened)
    Opens or closes the dialog.
    void
    setOverlayRole(String role)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use setRole(String) instead
    void
    setResizable(boolean resizable)
    Sets whether dialog can be resized by user or not.
    void
    setRole(String role)
    Sets the ARIA role for the dialog element, used by screen readers.
    void
    setTop(String top)
    Sets the top position of the dialog.
    void
    setVisible(boolean visible)
    Set the visibility of the dialog.
    void
    setWidth(String value)
     

    Methods inherited from class com.vaadin.flow.component.Component

    addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.vaadin.flow.component.HasComponents

    add, add, addComponentAsFirst, remove, remove, removeAll

    Methods inherited from interface com.vaadin.flow.component.HasElement

    getElement

    Methods inherited from interface com.vaadin.flow.component.HasEnabled

    isEnabled, setEnabled

    Methods inherited from interface com.vaadin.flow.component.HasSize

    getHeightUnit, getWidthUnit, setHeight, setHeightFull, setMaxHeight, setMaxWidth, setMinHeight, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidthFull

    Methods inherited from interface com.vaadin.flow.component.HasStyle

    addClassName, addClassNames, getClassName, getClassNames, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

    Methods inherited from interface com.vaadin.flow.component.HasTheme

    addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

    Methods inherited from interface com.vaadin.flow.component.shared.HasThemeVariant

    addThemeVariants, removeThemeVariants

  • Constructor Details

    • Dialog

      public Dialog()
      Creates an empty dialog.

    • Dialog

      public Dialog(com.vaadin.flow.component.Component... components)
      Creates a dialog with given components inside.
      Parameters:
      components - the components inside the dialog
      See Also:
      • HasComponents.add(Component...)

    • Dialog

      public Dialog(String title)
      Creates a dialog with given title.
      Parameters:
      title - the title of the component

    • Dialog

      public Dialog(String title, com.vaadin.flow.component.Component... components)
      Creates a dialog with given title and components inside.
      Parameters:
      title - the title of the component
      components - the components inside the dialog

  • Method Details

    • getTop

      public String getTop()
      Gets the top position of the dialog.
      Returns:
      the top position of the dialog

    • setTop

      public void setTop(String top)
      Sets the top position of the dialog. If a unitless number is provided, pixels are assumed.

      Note that the dialog top edge may not be the same as the viewport top edge (e.g. the "Lumo" theme defines some spacing to prevent the dialog from stretching all the way to the top of the viewport).

      Parameters:
      top - the top position of the dialog

    • getLeft

      public String getLeft()
      Gets the left position of the dialog.
      Returns:
      the left position of the dialog

    • setLeft

      public void setLeft(String left)
      Sets the distance of the dialog from the left of its container. If a unitless number is provided, pixels are assumed.

      Note that the dialog left edge may not be the same as the viewport left edge (e.g. the "Lumo" theme defines some spacing to prevent the dialog from stretching all the way to the left of the viewport).

      Parameters:
      left - the left position of the dialog

    • setWidth

      public void setWidth(String value)
      Specified by:
      setWidth in interface com.vaadin.flow.component.HasSize

    • setMinWidth

      public void setMinWidth(String value)
      Specified by:
      setMinWidth in interface com.vaadin.flow.component.HasSize

    • setMaxWidth

      public void setMaxWidth(String value)
      Specified by:
      setMaxWidth in interface com.vaadin.flow.component.HasSize

    • setHeight

      public void setHeight(String value)
      Specified by:
      setHeight in interface com.vaadin.flow.component.HasSize

    • setMinHeight

      public void setMinHeight(String value)
      Specified by:
      setMinHeight in interface com.vaadin.flow.component.HasSize

    • setMaxHeight

      public void setMaxHeight(String value)
      Specified by:
      setMaxHeight in interface com.vaadin.flow.component.HasSize

    • getWidth

      public String getWidth()
      Specified by:
      getWidth in interface com.vaadin.flow.component.HasSize

    • getMinWidth

      public String getMinWidth()
      Specified by:
      getMinWidth in interface com.vaadin.flow.component.HasSize

    • getMaxWidth

      public String getMaxWidth()
      Specified by:
      getMaxWidth in interface com.vaadin.flow.component.HasSize

    • getHeight

      public String getHeight()
      Specified by:
      getHeight in interface com.vaadin.flow.component.HasSize

    • getMinHeight

      public String getMinHeight()
      Specified by:
      getMinHeight in interface com.vaadin.flow.component.HasSize

    • getMaxHeight

      public String getMaxHeight()
      Specified by:
      getMaxHeight in interface com.vaadin.flow.component.HasSize

    • addDialogCloseActionListener

      public com.vaadin.flow.shared.Registration addDialogCloseActionListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogCloseActionEvent> listener)
      Add a listener that controls whether the dialog should be closed or not.

      The listener is informed when the user wants to close the dialog by clicking outside the dialog, or by pressing escape. Then you can decide whether to close or to keep opened the dialog. It means that dialog won't be closed automatically unless you call close() method explicitly in the listener implementation.

      NOTE: adding this listener changes behavior of the dialog. Dialog is closed automatically in case there are no any close listeners. And the close() method should be called explicitly to close the dialog in case there are close listeners.

      Parameters:
      listener - the listener to add
      Returns:
      registration for removal of listener
      See Also:

    • addResizeListener

      public com.vaadin.flow.shared.Registration addResizeListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogResizeEvent> listener)
      Adds a listener that is called after the user finishes resizing the dialog. It is called only if resizing is enabled (see setResizable(boolean)).

      Note: By default, the component will sync the width/height and top/left values after every resizing.

      Parameters:
      listener - the listener to add
      Returns:
      registration for removal of listener

    • addDraggedListener

      public com.vaadin.flow.shared.Registration addDraggedListener(com.vaadin.flow.component.ComponentEventListener<Dialog.DialogDraggedEvent> listener)
      Adds a listener that is called after the user finishes dragging the dialog. It is called only if dragging is enabled (see setDraggable(boolean)).

      Note: By default, the component will sync the top/left values after every dragging.

      Parameters:
      listener - the listener to add
      Returns:
      registration for removal of listener

    • add

      public void add(Collection<com.vaadin.flow.component.Component> components)
      Adds the given components into this dialog.
      Specified by:
      add in interface com.vaadin.flow.component.HasComponents
      Parameters:
      components - the components to add

    • addComponentAtIndex

      public void addComponentAtIndex(int index, com.vaadin.flow.component.Component component)
      Adds the given component into this dialog at the given index.
      Specified by:
      addComponentAtIndex in interface com.vaadin.flow.component.HasComponents
      Parameters:
      index - the index, where the component will be added.
      component - the component to add

    • isCloseOnEsc

      public boolean isCloseOnEsc()
      Gets whether this dialog can be closed by hitting the esc-key or not.

      By default, the dialog is closable with esc.

      Returns:
      true if this dialog can be closed with the esc-key, false otherwise

    • setCloseOnEsc

      public void setCloseOnEsc(boolean closeOnEsc)
      Sets whether this dialog can be closed by hitting the esc-key or not.

      By default, the dialog is closable with esc.

      Parameters:
      closeOnEsc - true to enable closing this dialog with the esc-key, false to disable it

    • isCloseOnOutsideClick

      public boolean isCloseOnOutsideClick()
      Gets whether this dialog can be closed by clicking outside of it or not.

      By default, the dialog is closable with an outside click.

      Returns:
      true if this dialog can be closed by an outside click, false otherwise

    • setCloseOnOutsideClick

      public void setCloseOnOutsideClick(boolean closeOnOutsideClick)
      Sets whether this dialog can be closed by clicking outside of it or not.

      By default, the dialog is closable with an outside click.

      Parameters:
      closeOnOutsideClick - true to enable closing this dialog with an outside click, false to disable it

    • open

      public void open()
      Opens the dialog.

      If a dialog was not added manually to a parent component, it will be automatically added to the UI when opened, and automatically removed from the UI when closed. Note that the dialog is then scoped to the UI, and not the current view. As such, when navigating away from a view, the dialog will still be opened or stay open. In order to close the dialog when navigating away from a view, it should either be explicitly added as a child to the view, or it should be explicitly closed when leaving the view.

    • close

      public void close()
      Closes the dialog.

      This automatically removes the dialog from the UI, unless it was manually added to a parent component.

    • setModal

      public void setModal(boolean modal)
      Sets whether component will open modal or modeless dialog.

      Note: When dialog is set to be modeless, then it's up to you to provide means for it to be closed (eg. a button that calls close()). The reason being that a modeless dialog allows user to interact with the interface under it and won't be closed by clicking outside or the ESC key.

      Parameters:
      modal - false to enable dialog to open as modeless modal, true otherwise.

    • isModal

      public boolean isModal()
      Gets whether component is set as modal or modeless dialog.
      Returns:
      true if modal dialog (default), false otherwise.

    • setDraggable

      public void setDraggable(boolean draggable)
      Sets whether dialog is enabled to be dragged by the user or not.

      To allow an element inside the dialog to be dragged by the user (for instance, a header inside the dialog), a class "draggable" can be added to it (see HasStyle.addClassName(String)).

      Note: If draggable is enabled and dialog is opened without first being explicitly attached to a parent, then it won't restore its last position in the case the user closes and opens it again. Reason being that a self attached dialog is removed from the DOM when it's closed and position is not synched.

      Parameters:
      draggable - true to enable dragging of the dialog, false otherwise

    • isDraggable

      public boolean isDraggable()
      Gets whether dialog is enabled to be dragged or not.
      Returns:
      true if dragging is enabled, false otherwise (default).

    • setResizable

      public void setResizable(boolean resizable)
      Sets whether dialog can be resized by user or not.
      Parameters:
      resizable - true to enabled resizing of the dialog, false otherwise.

    • isResizable

      public boolean isResizable()
      Gets whether dialog is enabled to be resized or not.
      Returns:
      true if resizing is enabled, falsoe otherwiser (default).

    • setHeaderTitle

      public void setHeaderTitle(String title)
      Sets the title to be rendered on the dialog header.
      Parameters:
      title - title to be rendered

    • getHeaderTitle

      public String getHeaderTitle()
      Gets the title set for the dialog header.
      Returns:
      the title or an empty string, if a header title is not defined.

    • getHeader

      public Dialog.DialogHeader getHeader()
      Gets the object from which components can be added or removed from the dialog header area. The header is displayed only if there's a getHeaderTitle() or at least one component added with HasComponents.add(Component...).
      Returns:
      the header object

    • getFooter

      public Dialog.DialogFooter getFooter()
      Gets the object from which components can be added or removed from the dialog footer area. The footer is displayed only if there's at least one component added with HasComponents.add(Component...).
      Returns:
      the header object

    • setVisible

      public void setVisible(boolean visible)
      Set the visibility of the dialog.

      For a modal dialog the server-side modality will be removed when dialog is not visible so that interactions can be made in the application.

      Overrides:
      setVisible in class com.vaadin.flow.component.Component
      Parameters:
      visible - dialog visibility
      See Also:
      • Component.setVisible(boolean)

    • setOpened

      public void setOpened(boolean opened)
      Opens or closes the dialog.

      If a dialog was not added manually to a parent component, it will be automatically added to the UI when opened, and automatically removed from the UI when closed. Note that the dialog is then scoped to the UI, and not the current view. As such, when navigating away from a view, the dialog will still be opened or stay open. In order to close the dialog when navigating away from a view, it should either be explicitly added as a child to the view, or it should be explicitly closed when leaving the view.

      Parameters:
      opened - true to open the dialog, false to close it

    • isOpened

      @Synchronize(property="opened", value="opened-changed", allowInert=true) public boolean isOpened()
      Gets the open state from the dialog.
      Returns:
      the opened property from the dialog

    • addOpenedChangeListener

      public com.vaadin.flow.shared.Registration addOpenedChangeListener(com.vaadin.flow.component.ComponentEventListener<Dialog.OpenedChangeEvent> listener)
      Add a listener for when the dialog's opened state changes.

      Note that this event fires immediately when the opened property changes, which, when closing the dialog, is before the closing animation has finished. To wait for the animation to finish, use addClosedListener(ComponentEventListener).

      Parameters:
      listener - the listener to add
      Returns:
      a Registration for removing the event listener

    • addClosedListener

      public com.vaadin.flow.shared.Registration addClosedListener(com.vaadin.flow.component.ComponentEventListener<Dialog.ClosedEvent> listener)
      Add a lister for when the dialog's closing animation has finished. Can be used to remove the dialog from the UI afterward.
      Parameters:
      listener - the listener to add
      Returns:
      a Registration for removing the event listener

    • addAttachListener

      public com.vaadin.flow.shared.Registration addAttachListener(com.vaadin.flow.component.ComponentEventListener<com.vaadin.flow.component.AttachEvent> listener)

      Note: To listen for opening the dialog, you should use addOpenedChangeListener(ComponentEventListener).

      Specified by:
      addAttachListener in interface com.vaadin.flow.component.AttachNotifier

    • addDetachListener

      public com.vaadin.flow.shared.Registration addDetachListener(com.vaadin.flow.component.ComponentEventListener<com.vaadin.flow.component.DetachEvent> listener)

      Note: To listen for closing the dialog, you should use addClosedListener(ComponentEventListener), as the component is not necessarily removed from the DOM when closing.

      Specified by:
      addDetachListener in interface com.vaadin.flow.component.DetachNotifier

    • onAttach

      protected void onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
      Overrides:
      onAttach in class com.vaadin.flow.component.Component

    • setRole

      public void setRole(String role)
      Sets the ARIA role for the dialog element, used by screen readers.
      Parameters:
      role - the role to set

    • setOverlayRole

      @Deprecated(since="25.0", forRemoval=true) public void setOverlayRole(String role)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use setRole(String) instead
      Sets the ARIA role for the dialog element, used by screen readers.
      Parameters:
      role - the role to set

    • getRole

      public String getRole()
      Gets the ARIA role for the dialog element, used by screen readers. Defaults to dialog.
      Returns:
      the role

    • getOverlayRole

      @Deprecated(since="25.0", forRemoval=true) public String getOverlayRole()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getRole() instead
      Gets the ARIA role for the dialog element, used by screen readers. Defaults to dialog.
      Returns:
      the role

    • getAriaLabel

      protected String getAriaLabel()
      Set the aria-label attribute for assistive technologies like screen readers. An undefined value for this property (the default) means that the aria-label attribute is not present at all.

      This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

      Returns:
      the ariaLabel property from the webcomponent

    • setAriaLabel

      protected void setAriaLabel(String ariaLabel)
      Set the aria-label attribute for assistive technologies like screen readers. An undefined value for this property (the default) means that the aria-label attribute is not present at all.
      Parameters:
      ariaLabel - the String value to set

    • getStyle

      public com.vaadin.flow.dom.Style getStyle()
      Specified by:
      getStyle in interface com.vaadin.flow.component.HasStyle
      Throws:
      UnsupportedOperationException - Dialog does not support adding styles