--- title: "dialog" description: "Overview" permalink: /docs/build/ui-components/all-ui-components/dialog/ --- # dialog ## Overview The `dialog` UI component appears as a blocking overlay that provides information or confirms destructive behavior. They often prompt users to make a decision. Version compatibility `dialog` was introduced in version **4.58.0** of the JourneyApps Runtime. This `dialog` component is generated from the view's XML. For dialogs triggered from JavaScript/TypeScript, see [the journey.dialog documentation](/docs/build/js-ts-apis/journey/journey.dialog/). A `dialog` can currently not be shown upon entering a view (e.g. by calling it from the `init()` or `resume()` function). ### `dialog` use cases There are 3 main use cases for `dialog`. These are described in more detail below. 1. [Simple](#simple) dialogs 2. [Confirmation](#confirmation) dialogs 3. [Composition](#composition) dialogs #### Simple A simple `dialog` displays information to the user and does not require the user to make a decision, thus can be dismissed by selecting the primary button, hitting the `Esc` key or back button. Use simple dialogs sparingly as they are interruptive. Rather, less obtrusive [notifications](/docs/build/ui-components/all-ui-components/notification/) can be used. **Example** **main.view\.xml** ```xml ``` **main.js** ```javascript function onEnrollment() { component.dialog({id: "success-dialog"}).show(); } ``` ![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-4b2967ad9778bccb87fa3334c9c19372f5f7d61d-2fdialog-simple-example-0c4be93b.png) #### Confirmation A confirmation `dialog` gives the user the ability to provide final confirmation of a decision before committing to it. If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog by selecting the secondary button. **Example** **main.view\.xml** ```xml ``` **main.js** ```javascript function showResetSettings() { component.dialog({id: "reset-settings"}).show(); } function resetSettings(ok){ if (ok) { // Logic here } else { // Other logic here } } ``` ![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-ed1800acf0b8d9614a8708074350c4e200e2bafa-2fdialog-confirmation-example-82e9fe07.png) #### Composition A composition dialogs allows developers to embed other UI components inside it, therefore offering a wide range of input options. To embed a UI component to the `dialog`, add it inside a `body` tag. Refer to the syntax for more detail. **Example**: **main.view\.xml** ```xml ``` **main.js** ```javascript // JS function getStockTitle(){ return view.cur_item.name; } function onCancel() { // Logic for when the user selects Cancel } function onSubmit() { // Logic for when the user selects Save } ``` ![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-8742c6ecf403cc72f4216fe89fb4cf6eea9ca45c-2fdialog-composition-example-b694fa38.png) ## Standard Attributes ### `title` ```xml ``` A `dialog`'s `title` communicates its purpose to the user. Titles should: * Contain a brief, clear statement or question * Summarize the dialog's content * Avoid the following: * apologies (“Sorry for the interruption”) * alarm (“Warning!”) * ambiguity (“Are you sure?”) ```xml ``` ```javascript function onTaskComplete() { component.dialog({id: "task-complete"}).show(); } ``` ## Advanced Attributes ### `auto-hide` ```xml ``` By default the dialog will automatically hide when the user selects any of its buttons. To override this behavior, specify `auto-hide="false"`. When specifying `auto-hide="false"`, you are responsible for hiding the dialog using `component.dialog({id:'myId'}).hide()`. ```xml ``` ```javascript function showTsAndCs() { component.dialog({id: "tc-dialog"}).show(); } function agree(predicate){ if (predicate){ component.dialog({id: "tc-dialog"}).hide(); // Other success logic here } else { var ok = confirmDialog('By not agreeing to these terms, you void your warranty.\n Are you sure?'); if (ok) { component.dialog({id: "tc-dialog"}).hide(); // Other logic here } // The dialog will not hide and the user may change their selection } } ``` ### `on-cancel` **Triggered when**: The secondary button on a confirmation dialog is selected. **Event parameter**: Empty by default. Can be a user-defined variable or field. **Return value**: `undefined`, or the user-defined variable or field `on-cancel` is an event that calls a JS/TS [`$:function`](/docs/app-features/calling-js-functions-from-xml/) or [navigation](/docs/get-started/journeyapps-fundamentals/view-navigation/). See more details: - [js ts events](/docs/build/ui-components/js-ts-events/) **main.view\.xml** ```xml ``` **main.js** ```javascript function askLocation() { component.dialog({id: "use-location"}).show(); } function useLocation(ok){ if (ok) { // Logic for on-submit here } else { // Logic for on-cancel here } } ``` Specifying `on-cancel` will change the dialog to a confirmation dialog, with a secondary and primary button. ### `on-submit` **Triggered when**: The primary button (for simple dialogs) or submit button (for multi-button dialogs) on a dialog is selected. **Event parameter**: Empty by default. Can be a user-defined variable or field. **Return value**: `undefined`, or the user-defined variable or field. `on-submit` is an event that calls a JS/TS [`$:function`](/docs/app-features/calling-js-functions-from-xml/) or [navigation](/docs/get-started/journeyapps-fundamentals/view-navigation/). See more details: - [js ts events](/docs/build/ui-components/js-ts-events/) See example for [`on-cancel`](#on-cancel). `on-submit` will not trigger when a simple dialog is dismissable by selecting on the backdrop or the user pressing Esc key. ### `submit-text` and `cancel-text` ```xml ``` The `submit-text` and `cancel-text` attributes allows for changing the default text on the dialog. Be as specific as possible with button copy to avoid ambiguity. Instead of "Yes", rather repeat the action that a button will trigger - for example "Discard", "Save" or "Reset" ```xml ``` ```javascript function showTsAndCs() { component.dialog({id: "tc-dialog"}).show(); } function agree(ok){ if (ok) { // Logic here } else { // Other logic here } } ``` ### `subtext` ```xml ``` Subtext provides more detail to the user about the purpose of the dialog. The `subtext` attribute can be a [format string](/docs/app-features/xml-format-strings/) and it also supports newline characters. ```xml ``` ```javascript function onTaskAdded() { component.dialog({id: "task-added"}).show(); } function getJobId() { return view.currentJob.id_code; } ``` ## Common Attributes ### `border-radius` ### `border-width` ### `border-color` ### `border-style` ### `id` ```xml ``` The `id` attribute is required to target a particular dialog to call `show()` or `hide()` on it. ```xml ``` ```javascript function onTaskComplete() { component.dialog({id: "task-complete"}).show(); } function onTaskUploadFail() { component.dialog({id: "task-complete"}).hide(); } ``` See also: ## Component Methods The following component methods are available when an [`id`](/docs/build/ui-components/common-attributes/id/) is assigned to the component and `component.dialog({id:'my-id'})` is called from JS/TS: ### `scrollIntoView` Programmatically scroll until the component is visible in the view.