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.
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 page.
Rather than cluttering your .vue templates with QDialogs, it’s best if you write a component for your dialog and use the Dialog Plugin to invoke it from anywhere in your app.
Usage
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 <div> tag (or wrap it with one yourself).
Basic
Styling
Positioning
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”.
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:
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
Different modes
User cannot dismiss the Dialog by pressing ESCAPE key or by clicking/tapping on its backdrop.
Dialogs can also be a part of the page, without requiring immediate focus. It’s where “seamless” mode comes into play:
Dialog in dialog
You are able to open dialogs on top of other dialogs, with infinite number of depth levels.
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:
Accessibility v2.25+
QDialog follows the WAI-ARIA dialog pattern: 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.
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:
// 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
}
}
}
}