--- title: Dialog related: - title: Dialog Plugin path: ../quasar-plugins/dialog.md - title: v-close-popup directive path: ../vue-directives/close-popup.md - title: Card path: card.md - title: Popup Proxy path: popup-proxy.md --- The QDialog component is a great way to offer the user the ability to choose a specific action or list of actions. They also can provide the user with important information, or require them to make a decision (or multiple decisions). From a UI perspective, you can think of Dialogs as a type of floating modal, which covers only a portion of the screen. This means Dialogs should only be used for quick user actions, like verifying a password, getting a short App notification or selecting an option or options quickly. > [!TIP] > Dialogs can also be used as a globally available method for more basic use cases, like the native JS alert(), prompt(), etc. For the latter behaviour, go to [Dialog Plugin](../quasar-plugins/dialog.md) page. > [!TIP] > **Masterclass TIP** > > Rather than cluttering your .vue templates with QDialogs, it's best if you write a component for your dialog and use the [Dialog Plugin](../quasar-plugins/dialog.md#invoking-custom-component) to invoke it from anywhere in your app. ## QDialog API ### Props - `transition-show` (string, optional), default `'fade'` One of Quasar's embedded transitions Examples: `'fade'`, `'slide-down'` - `transition-hide` (string, optional), default `'fade'` One of Quasar's embedded transitions Examples: `'fade'`, `'slide-down'` - `transition-duration` (string | number, optional), default `300` Transition duration (in milliseconds, without unit) - `model-value` (boolean, optional), default `null` Model of the component defining shown/hidden state; Either use this property (along with a listener for 'update:model-value' event) OR use v-model directive Examples: `v-model="state"` - `persistent` (boolean, optional) User cannot dismiss Dialog if clicking outside of it or hitting ESC key; Also, an app route change won't dismiss it - `no-esc-dismiss` (boolean, optional) User cannot dismiss Dialog by hitting ESC key; No need to set it if 'persistent' prop is also set - `no-backdrop-dismiss` (boolean, optional) User cannot dismiss Dialog by clicking outside of it; No need to set it if 'persistent' prop is also set - `no-route-dismiss` (boolean, optional) Changing route app won't dismiss Dialog; No need to set it if 'persistent' prop is also set - `auto-close` (boolean, optional) Any click/tap inside of the dialog will close it - `seamless` (boolean, optional) Put Dialog into seamless mode; Does not use a backdrop so user is able to interact with the rest of the page too - `backdrop-filter` (string, optional) *(added v2.15)* Apply a backdrop filter; The value needs to be the same as in the CSS specs for backdrop-filter; The examples are not an exhaustive list Examples: - `'blur(4px)'` - `'blur(4px) saturate(150%)'` - `'brightness(60%)'` - `'invert(70%)'` - `'grayscale(100%)'` - `'contrast(40%)'` - `'hue-rotate(120deg)'` - `'sepia(90%)'` - `'saturate(80%)'` - `'none'` - `maximized` (boolean, optional) Put Dialog into maximized mode - `full-width` (boolean, optional) Dialog will try to render with same width as the window - `full-height` (boolean, optional) Dialog will try to render with same height as the window - `position` (string, optional), default `'standard'` Stick dialog to one of the sides (top, right, bottom or left) Accepts: `'standard'`, `'top'`, `'right'`, `'bottom'`, `'left'` - `square` (boolean, optional) Forces content to have squared borders - `no-refocus` (boolean, optional) (Accessibility) When Dialog gets hidden, do not refocus on the DOM element that previously had focus - `no-focus` (boolean, optional) (Accessibility) When Dialog gets shown, do not switch focus on it - `no-shake` (boolean, optional) Do not shake up the Dialog to catch user's attention - `allow-focus-outside` (boolean, optional) Allow elements outside of the Dialog to be focusable; By default, for accessibility reasons, QDialog does not allow outer focus ### Computed Props - `contentEl` (Element, optional) The DOM Element of the rendered content ### Methods - `show(evt?: Event): void` Triggers component to show Params: - `evt` (Event, optional) JS event object - `hide(evt?: Event): void` Triggers component to hide Params: - `evt` (Event, optional) JS event object - `toggle(evt?: Event): void` Triggers component to toggle between show/hide Params: - `evt` (Event, optional) JS event object - `focus(selector?: string): void` Focus dialog; if you have content with autofocus attribute, it will directly focus it Params: - `selector` (string, optional) Optional CSS selector to override default focusable element Examples: `'[tabindex]:not([tabindex="-1"])'` - `shake(focusTarget?: Element): void` Shakes dialog Params: - `focusTarget` (Element, optional) Optional DOM Element to be focused after shake Examples: `document.getElementById('example')` ### Events - `@update:model-value` Emitted when showing/hidden state changes; Is also used by v-model Params: - `value` (boolean, optional) New state (showing/hidden) - `@show` Emitted after component has triggered show() Params: - `evt` (Event, required) JS event object - `@before-show` Emitted when component triggers show() but before it finishes doing it Params: - `evt` (Event, required) JS event object - `@hide` Emitted after component has triggered hide() Params: - `evt` (Event, required) JS event object - `@before-hide` Emitted when component triggers hide() but before it finishes doing it Params: - `evt` (Event, required) JS event object - `@shake` Emitted when the Dialog shakes in order to catch user's attention, unless the 'no-shake' property is set - `@escape-key` Emitted when ESC key is pressed; Does not get emitted if Dialog is 'persistent' or it has 'no-esc-dismiss' set ### Slots - `#default` Default slot in the devland unslotted content of the component ## Usage > [!IMPORTANT] > It's best that your QDialog main content is a QCard. However, if you are planning on using any other component (like QForm) or tag, make sure that the direct child of QDialog is rendered with a `
` tag (or wrap it with one yourself). ### Basic ```vue ``` ### Styling ```vue ``` Example "Backdrop filter (v2.14.8+)": ```vue ``` ### Positioning Example "Positions": ```vue ``` > [!NOTE] > Do not mistake "position" prop with the show/hide animation. If you want a custom animation, you should use `transition-show` and `transition-hide` which can be applied regardless of "position" or "maximized". Example "Maximized": ```vue ``` > [!NOTE] > **iOS** > > On iOS the soft keyboard does not shrink the page, so a dialog (especially a bottom-anchored one) could end up under it when one of its fields gets focused. QDialog keeps itself within the visible part of the screen while the keyboard is open. ### Various content Dialogs can contain any content. Some examples: ```vue ``` Example "With containerized QLayout": ```vue ``` > [!IMPORTANT] > If you are going to use the containerized QLayout, you'll need to put a width on your QDialog, if using left/right position, or a height, if using top/bottom position. You can use vw and vh units. ### Handling scroll Example "Scrollable dialogs": ```vue ``` ### Different modes User cannot dismiss the Dialog by pressing ESCAPE key or by clicking/tapping on its backdrop. Example "Persistent": ```vue ``` Dialogs can also be a part of the page, without requiring immediate focus. It's where "seamless" mode comes into play: Example "Seamless": ```vue ``` ### Dialog in dialog You are able to open dialogs on top of other dialogs, with infinite number of depth levels. Example "Inception": ```vue ``` ### Sizing You are able to customize the size of the Dialogs. Notice we either tamper with the content's style or we use `full-width` or `full-height` props: Example "Sizing examples": ```vue ``` ## Accessibility *(v2.25+)* QDialog follows the [WAI-ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): the popup renders with `role="dialog"` and a managed `aria-modal` attribute — `"true"` while the dialog has a backdrop, while a `seamless` dialog (which does not block the rest of the page) keeps the dialog role but announces `aria-modal="false"`. Focus is managed for you. On open, it moves into the dialog — to the first element bearing an `autofocus` (or `data-autofocus`) attribute, or to the dialog body itself when there is none. While the dialog is modal, focus that strays outside of it gets recaptured back in, and on close it returns to the element that opened the dialog. The `no-focus`, `no-refocus` and `allow-focus-outside` props opt out of each of these behaviors, should you need to manage focus yourself. Escape dismisses the dialog — a `persistent` dialog responds with its "shake" animation instead. > [!WARNING] > One thing QDialog cannot do for you is provide an accessible name — by default it is announced as an unnamed dialog. Pass an `aria-label`, or better, give your title element an `id` and reference it with `aria-labelledby`; both are attributes that fall through onto the `role="dialog"` element. ## Cordova/Capacitor back button Quasar handles the back button for you by default so it can hide any opened Dialogs instead of the default behavior which is to return to the previous page (which is not a nice user experience). However, should you wish to disable this behavior, edit your `/quasar.config` file: Example "For Capacitor": ```js // quasar.config file return { framework: { config: { capacitor: { // Quasar handles app exit on mobile phone back button. backButtonExit: true/false/'*'/['/login', '/home', '/my-page'], // On the other hand, the following completely // disables Quasar's back button management. backButton: true/false } } } } ``` Example "For Cordova": ```js // quasar.config file return { framework: { config: { cordova: { // Quasar handles app exit on mobile phone back button. backButtonExit: true/false/'*'/['/login', '/home', '/my-page'], // On the other hand, the following completely // disables Quasar's back button management. backButton: true/false } } } } ```