Skip to main content

Dialog

The ui5-dialog component is used to temporarily display some information in a size-limited window in front of the regular app screen. It is used to prompt the user for an action or a confirmation. The ui5-dialog interrupts the current app processing as it is the only focused UI element and the main screen is dimmed/blocked. The dialog combines concepts known from other technologies where the windows have names such as dialog box, dialog window, pop-up, pop-up window, alert box, or message box.

The ui5-dialog is modal, which means that an user action is required before it is possible to return to the parent window. To open multiple dialogs, each dialog element should be separate in the markup. This will ensure the correct modal behavior. Avoid nesting dialogs within each other. The content of the ui5-dialog is fully customizable.

Structure​

A ui5-dialog consists of a header, content, and a footer for action buttons. The ui5-dialog is usually displayed at the center of the screen. Its position can be changed by the user. To enable this, you need to set the property draggable accordingly.

Responsive Behavior​

The stretch property can be used to stretch the ui5-dialog on full screen.

Note: When a ui5-bar is used in the header or in the footer, you should remove the default dialog's paddings.

For more information see the sample "Bar in Header/Footer".

Keyboard Handling​

Basic Navigation​

When the ui5-dialog has the draggable property set to true and the header is focused, the user can move the dialog with the following keyboard shortcuts:

  • [Up] or [Down] arrow keys - Move the dialog up/down.
  • [Left] or [Right] arrow keys - Move the dialog left/right.

Resizing​

When the ui5-dialog has the resizable property set to true and the header is focused, the user can change the size of the dialog with the following keyboard shortcuts:

  • [Shift] + [Up] or [Down] - Decrease/Increase the height of the dialog.
  • [Shift] + [Left] or [Right] - Decrease/Increase the width of the dialog.

ES6 Module Import​

import "@ui5/webcomponents/dist/Dialog";

Note: We recommend placing popup-like components (ui5-dialog and ui5-popover) outside any other components. Preferably, the popup-like components should be placed in an upper level HTML element. Otherwise, in some cases the parent HTML elements can break the position and/or z-index management of the popup-like components.

Note: We don't recommend nesting popup-like components (ui5-dialog, ui5-popover).

Basic Sample​

Properties​

headerText​

DescriptionDefines the header text.
Note: If header slot is provided, the headerText is ignored.
Typestring
Default""

stretch​

DescriptionDetermines whether the component should be stretched to fullscreen.
Note: The component will be stretched to approximately 90% of the viewport.
Typeboolean
Defaultfalse

draggable​

DescriptionDetermines whether the component is draggable. If this property is set to true, the Dialog will be draggable by its header.
Note: The component can be draggable only in desktop mode.
Note: This property overrides the default HTML "draggable" attribute native behavior. When "draggable" is set to true, the native browser "draggable" behavior is prevented and only the Dialog custom logic ("draggable by its header") works.
Typeboolean
Defaultfalse
Since1.0.0-rc.9

resizable​

DescriptionConfigures the component to be resizable. If this property is set to true, the Dialog will have a resize handle in its bottom right corner in LTR languages. In RTL languages, the resize handle will be placed in the bottom left corner.
Note: The component can be resizable only in desktop mode.
Note: Upon resizing, externally defined height and width styling will be ignored.
Typeboolean
Defaultfalse
Since1.0.0-rc.10

state​

DescriptionDefines the state of the Dialog.
Note: If "Error" and "Warning" state is set, it will change the accessibility role to "alertdialog", if the accessibleRole property is set to "Dialog".
Type"None" | "Success" | "Warning" | "Error" | "Information"
Default"None"
Since1.0.0-rc.15

initialFocus​

DescriptionDefines the ID of the HTML Element, which will get the initial focus.
Typestring
Default""

preventFocusRestore​

DescriptionDefines if the focus should be returned to the previously focused element, when the popup closes.
Typeboolean
Defaultfalse
Since1.0.0-rc.8

open​

DescriptionIndicates if the element is open
Typeboolean
Defaultfalse
Since1.2.0

accessibleName​

DescriptionDefines the accessible name of the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleNameRef​

DescriptionDefines the IDs of the elements that label the component.
Typestring
Default""
Since1.1.0

accessibleRole​

DescriptionAllows setting a custom role.
Type"None" | "Dialog" | "AlertDialog"
Default"Dialog"
Since1.10.0

Slots​

DescriptionDefines the header HTML Element.
Note: When a ui5-bar is used in the header, you should remove the default dialog's paddings.
Note: If header slot is provided, the labelling of the dialog is a responsibility of the application developer. accessibleName should be used.
TypeArray<HTMLElement>
DescriptionDefines the footer HTML Element.
Note: When a ui5-bar is used in the footer, you should remove the default dialog's paddings.
TypeArray<HTMLElement>

default​

DescriptionDefines the content of the Popup.
TypeArray<HTMLElement>

Events​

before-open​

DescriptionFired before the component is opened. This event can be cancelled, which will prevent the popup from opening. This event does not bubble.
TypeCustomEvent

after-open​

DescriptionFired after the component is opened. This event does not bubble.
TypeCustomEvent

before-close​

DescriptionFired before the component is closed. This event can be cancelled, which will prevent the popup from closing. This event does not bubble.
TypeCustomEvent<PopupBeforeCloseEventDetail>
ParametersescPressed: boolean
Indicates that ESC key has triggered the event.

after-close​

DescriptionFired after the component is closed. This event does not bubble.
TypeCustomEvent

Methods​

show​

DescriptionShows the dialog.
Return typePromise<void>
ParameterspreventInitialFocus: boolean
Prevents applying the focus inside the popup

applyFocus​

DescriptionFocuses the element denoted by initialFocus, if provided, or the first focusable element otherwise.
Return typePromise<void>

isOpen​

DescriptionTells if the component is opened
Return typeboolean

close​

DescriptionCloses the popup.
Return typevoid

CSS Parts​

NameDescription
headerUsed to style the header of the component
contentUsed to style the content of the component
footerUsed to style the footer of the component

More Samples​

Draggable and Resizable​

Usage of Bar as header/footer​

The Bar component can be used as header and/or footer of the Dialog

Value States​

The Dialog supports "Success", "Warning", "Error" and "None"states via the "state" property.