Skip to main content

Dialog

<ui5-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 a 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 to full screen. For better usability, it's recommended to stretch the dialog to full screen on phone devices.

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";

Basic Sample​

Properties​

headerText​

DescriptionDefines the header text.
Note: If header slot is provided, the headerText is ignored.
Typestring | undefined
Defaultundefined

stretch​

DescriptionDetermines if the dialog will be stretched to full screen on mobile. On desktop, the dialog will be stretched to approximately 90% of the viewport.
Note: For better usability of the component it is recommended to set this property to "true" when the dialog is opened on phone.
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 "Negative" and "Critical" states is set, it will change the accessibility role to "alertdialog", if the accessibleRole property is set to "Dialog".
Type"None" | "Positive" | "Critical" | "Negative" | "Information"
Default"None"
Since1.0.0-rc.15

initialFocus​

DescriptionDefines the ID of the HTML Element, which will get the initial focus.
Note: If an element with autofocus attribute is added inside the component, initialFocus won't take effect.
Typestring | undefined
Defaultundefined

preventFocusRestore​

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

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 | undefined
Defaultundefined
Since1.1.0

accessibleRole​

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

preventInitialFocus​

DescriptionIndicates whether initial focus should be prevented.
Typeboolean
Defaultfalse
Since2.0.0

open​

DescriptionIndicates if the element is open
Typeboolean
Defaultfalse
Since1.2.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.
TypeCustomEvent
BubblesNo
CancelableYes - via preventDefault()

open​

DescriptionFired after the component is opened.
TypeCustomEvent
BubblesNo
CancelableNo

before-close​

DescriptionFired before the component is closed. This event can be cancelled, which will prevent the popup from closing.
TypeCustomEvent<PopupBeforeCloseEventDetail>
ParametersescPressed: boolean
Indicates that ESC key has triggered the event.
BubblesNo
CancelableYes - via preventDefault()

close​

DescriptionFired after the component is closed.
TypeCustomEvent
BubblesNo
CancelableNo

Methods​

applyFocus​

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

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

States​

The Dialog supports "Positive", "Critical", "Negative" and "None" states via the "state" property.