Dialog
Last updated
Was this helpful?
Last updated
Was this helpful?
Chat bots can embed dialog buttons in chat messages. When the dialog button is clicked, a dialog opens and displays the content that has been predefined. This can be useful to make long messages much more concise, or progressively disclose a form only if it is relevant to the user for example.
The Dialog component is structured in two sections:
<ui-action action='open-dialog'> tag. This tag defines where and how the will be displayed, and it references the dialog that will open using the target-id attribute;
<dialog> tag that defines the content of the dialog that will be displayed when the button is clicked.
The <ui-action> tag wraps a single <button> children tag. The button tag supports the usual styles (primary, secondary, tertiary). Examples are available at the bottom of this page.
The <ui-action> tag supports the following attributes:
Attribute
Type
Required?
Description
action
String
Yes
For Dialogs, always set to action='open-dialog'.
target-id
String
Yes
Id of the dialog that must be opened when user will trigger this ui-action.
See the id attribute in the <dialog> tag.
Each <dialog> is split in three areas (children tags):
<title> - mandatory: specifies the title of the dialog and is always displayed at the top of it in a fixed and non scrollable position.
<body> - mandatory: specifies the content of the dialog that is displayed in the middle of it and can be scrollable when the content is too big to be contained in the view height.
<footer> - optional: specifies the footer of the dialog and is always displayed at the bottom in a fixed and non scrollable position.
The <dialog> tag supports the following attributes
Attribute
Type
Required?
Description
id
String
Yes
Id of the dialog that will be triggered thanks to the ui-action it is associated to. See target-id attribute in <ui-action> tag.
width
String
No.
Default to medium
Specifies the width of the dialog.
NB: values can be: small, medium, large, or full-width.
The following gif shows an example that contains two dialogs:
The first dialog is embedded in a form. You will notice that the button used to trigger the dialog is positioned where the <ui-action> tag is coded.
As soon as the associated <dialog> is at its same nesting level, it can be placed anywhere before or after the ui-action.
You can also notice that users can interact with the form as well as submit it.
However, the dialog only contains text as it cannot contain any interactive Form Elements. Please note that a cancel button can be included in the dialog as it is not considered as an interactive Form Element: you can use it to offer another option for the user to close the dialog.
Please note the scrolling behaviour of the body whereas both title and footer are placed in a fixed position.
The second dialog embeds a form instead.
After having started to fill-in the form, if the user closes the dialog and opens it back, the values of the fields will not reset to their original values, as long as the user does not refresh the page.
Also, when submitting a form that is in a dialog, the dialog will automatically close after a certain delay. If the user opens back the dialog without refreshing the page, then the values of the form and its state are persisted.
Below are simpler examples with and without the use of forms.
The max length of any ui-action or dialog attribute is 256.
Please note that the attribute type of the button is not supported when wrapped by a <ui-action> tag.
The dialog and ui-action tags must be both present in the same message, at the same nesting level, and they must share the same and unique id / target-id. Please note it is possible to have several dialogs in the same message as soon as each dialog has a different id.
The dialog feature is supported in popped-out mode. The dialog will open in the popped-out window.
Dialogs can be contained inside forms. However, if contained in a form, the dialog cannot contain any interactive Element (such as button, text-area, etc.)
Dialogs can contain a form. The <form> tag should wrap the entire content of the dialog, including the <title> ,<body> and <footer> tags, as you can see in the examples below. This is useful when you want the submit button not to be hidden and always appear in the footer of the dialog whereas the rest of the form content is contained in the scrollable body area.
A dialog cannot be embedded in another dialog.
Even if this possible, please avoid embedding more than one form in a single dialog.
Main features introduced
Agent needed to parse message sent by the bot
Client 2.0 release
Client 1.5 release
Backward client-compatibility behavior (e.g. external rooms)
Initial release
20.12.2
21.10
Not working
Not working - entire message is not rendered
The dialog functionality supports in the following way:
Please also note that users can close the dialog thanks to the cross (x) displayed at the top-right corner of it, as well as with a new type of that has been created for that purpose: <button type="cancel">. You can also specify the class attribute of the button which is by default set to "tertiary" for this new button.
