The Modal component is a dialog box or popup window that is displayed on top of the current page content. It is used to present critical information, request user input for a specific task, or show supplementary content without navigating away from the current page. When a modal is active, interaction with the underlying page content is typically disabled until the modal is dismissed or an action within it is taken.
When to use
- For tasks that require user focus and must be completed or dismissed before interacting with the rest of the page (e.g., creating a new item, confirming a critical action like deletion, or complex user settings).
- To display important information, warnings, or errors that need to interrupt the user's current flow and demand attention.
- For short forms that need to be completed in context.
When not to use / alternatives
- For very brief, non-critical notifications that don't need to interrupt the user (use Alerts or a Toast/Snackbar pattern instead).
- If the content or task is extensive and better suited for a dedicated page (e.g., a complex multi-step wizard or very long forms).
- For multi-step workflows that are too complex to be comfortably contained within a single modal (consider a series of distinct pages or a larger overlay/canvas if appropriate).
- When the information is not critical and does not need to halt user interaction with the main page (consider an inline expand/collapse section, a Popover for contextual information, or a non-modal Drawer/Offcanvas).
Component anatomy
A Lighthouse Modal typically consists of the following key parts:
- Backdrop: The semi-transparent overlay that covers the page content behind the modal. It visually de-emphasizes the underlying page and indicates that it is temporarily inactive.
- Modal Dialog: The main container for the modal itself. This element controls the modal's size, shape, and positioning on the screen.
- Modal Content: The visual wrapper within the Modal Dialog that holds the header, body, and footer sections. This part typically has its own background, border, and shadow.
- Modal Header (Optional): A section at the top of the Modal Content. It usually contains the modal title and an optional close (dismiss) button.
- Modal Title (Optional): Text that clearly describes the purpose or content of the modal.
- Modal Body: The primary content area of the modal. This section can contain text, forms, images, lists, and other components.
- Modal Footer (Optional): A section at the bottom of the Modal Content. It usually contains action buttons related to the modal's purpose (e.g., "Save," "Cancel," "Confirm," "Close").
- Close Button (Optional): Typically an "X" icon, often placed in the Modal Header, or a text button in the Modal Footer, allowing the user to dismiss the modal without completing an action.
Default Modal
The standard appearance and behavior, typically including a header, body, and footer.
Sizes
Modal Sizes: Lighthouse modals can be presented in various predefined widths to suit different content needs: - Small (sm): For brief messages, simple confirmations, or very short forms. - Width Token: modal-sm (Value: {q-size-320} or 320px) - Medium (md): The default size suitable for many common use cases. - Width Token: modal-md (Value: {q-size-580} or 580px) - Large (lg): For modals containing more extensive content or complex forms. - Width Token: modal-lg (Value: {q-size-890} or 890px) - Extra-Large (xl): For scenarios requiring a very wide content area within the modal. - Width Token: modal-xl (Value: {q-size-1140} or 1140px)
Alert
Alert modal
Success
Success modal
Functional Modals
Programmatically Create Modals using the useModalsUtilities composable from the NPM package.
Take a look at this advanced composable usage on QPortal: link.
Modal stack
Multiple modal support
Props
QModal
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | boolean | required | Controls visibility (use with v-model). |
title | string | "" | Modal header title text. |
titleHtml | string | "" | Modal header title as raw HTML (overrides title). |
titleTag | "h1"–"h6" | "h4" | HTML tag for the title element. |
size | "sm" | "lg" | "xl" | - | Modal width. |
centered | boolean | false | Vertically centers the modal in the viewport. |
scrollable | boolean | true | Makes the modal body scrollable when content overflows. |
okTitle | string | "Save" | Label for the OK/confirm button. |
okVariant | ButtonVariant | "primary" | Variant for the OK button. |
okDisabled | boolean | false | Disables the OK button. |
cancelTitle | string | "Cancel" | Label for the cancel button. |
cancelVariant | ButtonVariant | "outline-secondary" | Variant for the cancel button. |
cancelDisabled | boolean | false | Disables the cancel button. |
okOnly | boolean | false | Hides the cancel button, showing only the OK button. |
hideHeader | boolean | false | Hides the modal header. |
hideHeaderClose | boolean | false | Hides the close (×) button in the header. |
hideFooter | boolean | false | Hides the modal footer. |
noCloseOnBackdrop | boolean | false | Prevents closing when clicking the backdrop. |
noCloseOnEsc | boolean | false | Prevents closing when pressing Esc. |
noBackdrop | boolean | false | Removes the backdrop overlay. |
autoCloseOnOk | boolean | true | Automatically closes the modal when OK is clicked. |
imagePath | string | "" | Optional image shown in the modal header area. |
id | string | "" | HTML id for the root element. |
class | string | null | Additional CSS classes on the modal wrapper. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | boolean | Emitted when the modal opens or closes. Use with v-model. |
click-ok | — | Emitted when the OK button is clicked. |
click-cancel | — | Emitted when the cancel button is clicked. |
click-close | — | Emitted when the header close (×) button is clicked. |
show | — | Emitted before the modal starts to open. |
shown | — | Emitted after the modal has fully opened. |
hide | — | Emitted before the modal starts to close. |
hidden | — | Emitted after the modal has fully closed. |
Slots
| Slot | Description |
|---|---|
default | Main body content of the modal. |
modal-header | Replaces the entire default header. |
modal-title | Replaces only the title text in the header. |
modal-footer | Replaces the entire default footer. |
Accessibility
- The modal uses
role="dialog"andaria-modal="true"; thetitleormodal-titleslot provides the accessible name viaaria-labelledby - Focus is trapped inside the modal while it is open;
Esccloses the modal and returns focus to the trigger element - Ensure the trigger element (e.g. a button) has a meaningful label so screen readers can announce it before the modal opens
- When using
hideHeader, provide anaria-labelon the modal or a visually-hidden heading inside thedefaultslot - For destructive actions (e.g.
QModalConfirmDelete), usevariant="danger"on the OK button to visually reinforce the risk