Dialog

A dialog is a focused, overlay-based container used to present critical information or request user input that requires immediate attention. It appears above the application content, blocks underlying interaction, and guides the user toward a required decision or acknowledgement.

import {DialogModule} from "@qualcomm-ui/angular/dialog"

Examples

Sizes

The dialog component has two sizes: sm and md. Size governs the width of the dialog, as well as the content's spacing, font size, and padding.

<div q-dialog-root size="sm">
  <button emphasis="primary" q-button q-dialog-trigger variant="fill">
    Open Dialog (sm)
  </button>
  <dialog-content-demo />
</div>

Indicator Emphasis

Use the emphasis prop to change the intent and color of the dialog's indicator icon.

import {Component} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"
import type {QdsDialogEmphasis} from "@qualcomm-ui/qds-core/dialog"

@Component({
  imports: [DialogModule, ButtonModule],
  selector: "dialog-emphasis-demo",
  template: `
    <div class="flex flex-col gap-4">
      @for (color of emphasis; track color) {
        <div class="flex justify-center" q-dialog-root [emphasis]="color">
          <button q-button q-dialog-trigger size="sm" variant="outline">
            {{ color }}
          </button>
          <q-dialog-floating-portal>
            <div q-dialog-body>
              <button q-dialog-close-button></button>
              <h2 q-dialog-heading>Dialog Title</h2>
              <div q-dialog-description>Dialog Description</div>
            </div>
            <div q-dialog-footer>
              <button q-button q-dialog-close-trigger size="sm" variant="fill">
                Close
              </button>
            </div>
          </q-dialog-floating-portal>
        </div>
      }
    </div>
  `,
})
export class DialogEmphasisDemo {
  readonly emphasis: QdsDialogEmphasis[] = [
    "neutral",
    "info",
    "success",
    "warning",
    "danger",
  ]
}

Custom Indicator

Set a custom indicator icon by providing the q-dialog-indicator-icon directive within the q-dialog-body directive. Or hide it entirely using the hideIndicatorIcon property on the q-dialog-body directive.

<div q-dialog-body>
  <svg q-dialog-indicator-icon qIcon="AArrowDown"></svg>
  <button q-dialog-close-button></button>
  <h2 q-dialog-heading>Dialog Title</h2>
  <div q-dialog-description>Dialog Description</div>
</div>

Placement

Use the placement prop to change the placement of the dialog.

import {Component} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"
import type {QdsDialogPlacement} from "@qualcomm-ui/qds-core/dialog"

@Component({
  imports: [DialogModule, ButtonModule],
  selector: "dialog-placement-demo",
  template: `
    <div class="flex flex-col gap-4">
      @for (placement of placements; track placement) {
        <div class="flex justify-center" q-dialog-root [placement]="placement">
          <button q-button q-dialog-trigger size="sm" variant="outline">
            Open Dialog ({{ placement }})
          </button>
          <q-dialog-floating-portal>
            <div q-dialog-body>
              <button q-dialog-close-button></button>
              <h2 q-dialog-heading>Dialog Title</h2>
              <div q-dialog-description>Dialog Description</div>
            </div>
            <div q-dialog-footer>
              <button q-button q-dialog-close-trigger size="sm" variant="fill">
                Close
              </button>
            </div>
          </q-dialog-floating-portal>
        </div>
      }
    </div>
  `,
})
export class DialogPlacementDemo {
  placements: QdsDialogPlacement[] = ["top", "center", "bottom"]
}

Controlled State

Dialog visibility can be controlled using the open, openChanged and defaultOpen properties. These properties follow our controlled state pattern.

import {Component, signal} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"

@Component({
  imports: [DialogModule, ButtonModule],
  selector: "dialog-controlled-state-demo",
  template: `
    <div q-dialog-root [open]="open()" (openChanged)="onOpenChange($event)">
      <button emphasis="primary" q-button q-dialog-trigger variant="fill">
        Open Dialog
      </button>
      <q-dialog-floating-portal>
        <div q-dialog-body>
          <button q-dialog-close-button></button>
          <h2 q-dialog-heading>Dialog Title</h2>
          <div q-dialog-description>Dialog Description</div>
        </div>

        <div q-dialog-footer>
          <button q-button q-dialog-close-trigger size="sm" variant="fill">
            Close
          </button>
        </div>
      </q-dialog-floating-portal>
    </div>
  `,
})
export class DialogControlledStateDemo {
  readonly open = signal(false)

  onOpenChange(open: boolean) {
    console.debug("Dialog open changed:", open)
    this.open.set(open)
  }
}

Outside Scroll

The default scrollBehavior is outside, which makes the entire page scrollable when modal content exceeds viewport height. The modal and backdrop move with the page scroll instead of creating an internal scroll area within the modal.

import {Component} from "@angular/core"

import {LoremIpsumDirective} from "@qualcomm-ui/angular-core/lorem-ipsum"
import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"

@Component({
  imports: [DialogModule, ButtonModule, LoremIpsumDirective],
  selector: "dialog-outside-scroll-demo",
  template: `
    <div q-dialog-root>
      <button emphasis="primary" q-button q-dialog-trigger variant="fill">
        Open Dialog
      </button>
      <q-dialog-floating-portal>
        <div q-dialog-body>
          <button q-dialog-close-button></button>
          <h2 q-dialog-heading>Dialog Title</h2>
          <div q-dialog-description>
            <div numParagraphs="20" q-lorem-ipsum></div>
          </div>
        </div>
        <div q-dialog-footer>
          <button q-button q-dialog-close-trigger size="sm" variant="fill">
            Close
          </button>
        </div>
      </q-dialog-floating-portal>
    </div>
  `,
})
export class DialogOutsideScrollDemo {}

Inside Scroll

Set the scrollBehavior prop to inside to create an internal scroll area within the modal.

import {Component} from "@angular/core"

import {LoremIpsumDirective} from "@qualcomm-ui/angular-core/lorem-ipsum"
import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"

@Component({
  imports: [DialogModule, ButtonModule, LoremIpsumDirective],
  selector: "dialog-inside-scroll-demo",
  template: `
    <div q-dialog-root scrollBehavior="inside">
      <button emphasis="primary" q-button q-dialog-trigger variant="fill">
        Open Dialog
      </button>
      <q-dialog-floating-portal>
        <div q-dialog-body>
          <button q-dialog-close-button></button>
          <h2 q-dialog-heading>Dialog Title</h2>
          <div q-dialog-description>
            <div numParagraphs="20" q-lorem-ipsum></div>
          </div>
        </div>

        <div q-dialog-footer>
          <button q-button q-dialog-close-trigger size="sm" variant="outline">
            Close
          </button>
          <button
            emphasis="primary"
            q-button
            q-dialog-close-trigger
            size="sm"
            variant="fill"
          >
            Confirm
          </button>
        </div>
      </q-dialog-floating-portal>
    </div>
  `,
})
export class DialogInsideScrollDemo {}

Alert Dialog

Set the role prop to alertdialog to change the dialog component to an alert dialog. This is recommended for situations where the dialog is used to notify users of urgent information that demands their immediate attention.

import {Component} from "@angular/core"
import {Trash2} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {ButtonModule} from "@qualcomm-ui/angular/button"
import {DialogModule} from "@qualcomm-ui/angular/dialog"

@Component({
  imports: [DialogModule, ButtonModule],
  providers: [provideIcons({Trash2})],
  selector: "dialog-alert-dialog-demo",
  template: `
    <div emphasis="danger" q-dialog-root role="alertdialog">
      <button
        emphasis="danger"
        endIcon="Trash2"
        q-button
        q-dialog-trigger
        variant="outline"
      >
        Delete Account
      </button>
      <q-dialog-floating-portal>
        <div q-dialog-body>
          <button q-dialog-close-button></button>
          <h2 q-dialog-heading>Are you sure?</h2>
          <div q-dialog-description>
            This action cannot be undone. This will permanently delete your
            account and remove your data from our systems.
          </div>
        </div>
        <div q-dialog-footer>
          <button q-button q-dialog-close-trigger size="sm" variant="outline">
            Cancel
          </button>
          <button
            emphasis="danger"
            q-button
            q-dialog-close-trigger
            size="sm"
            variant="fill"
          >
            Confirm
          </button>
        </div>
      </q-dialog-floating-portal>
    </div>
  `,
})
export class DialogAlertDialogDemo {}

Shortcuts

<q-dialog-floating-portal>

A helper component that combines the portal, positioner, and content components. This shortcut is equivalent to:

<q-portal>
  <div q-dialog-backdrop></div>
  <div q-dialog-positioner>
    <section q-dialog-content><ng-content /></section>
  </div>
</q-portal>

API

<q-dialog-root>

The root component that provides context for the dialog and its parts.

Prop	Type	Default
aria-label Human-readable label for the dialog, used when the dialog title is not rendered	string
closeOnEscape Whether to close the dialog when the escape key is pressed	boolean	true
closeOnInteractOutside Whether to close the dialog when the outside is clicked	boolean	true
defaultOpen The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'	"ltr"
emphasis The style variant of the dialog's indicator.	\| 'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'	'neutral'
finalFocusEl Element to receive focus when the dialog is closed	() => HTMLElement
getRootNode A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
immediate Whether to synchronize the present change immediately or defer it to the next frame.	boolean	false
initialFocusEl Element to receive focus when the dialog is opened	() => HTMLElement
lazyMount When true, the component will not be rendered in the DOM until it becomes visible or active.	boolean	false
modal Whether to prevent pointer interaction outside the element and hide all content below it	boolean	true
open The controlled open state of the dialog	boolean
persistentElements The persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event	Array< () => Element >
placement The vertical placement of the dialog within the viewport. `'top'`: The dialog is positioned at the top of the viewport. `'center'`: The dialog is positioned at the center of the viewport. `'bottom'`: The dialog is positioned at the bottom of the viewport.	\| 'top' \| 'center' \| 'bottom'	'top'
present The controlled presence of the node.	boolean
preventScroll Whether to prevent scrolling behind the dialog when it's opened	boolean	true
restoreFocus Whether to restore focus to the element that had focus before the dialog was opened	boolean	true
role The dialog's role	\| 'dialog' \| 'alertdialog'	'dialog'
scrollBehavior Defines the scroll behavior of the dialog content when modal content exceeds viewport height. `'inside'`: The modal and backdrop create an internal scroll area within the modal. `'outside'`: The modal and backdrop move with the page scroll instead of creating an internal scroll area within the modal.	\| 'inside' \| 'outside'	'outside'
size The size of the dialog's content area and fonts. A smaller size uses less horizontal space.	'sm' \| 'md'	'sm'
skipAnimationOnMount Whether to allow the initial presence animation.	boolean	false
trapFocus Whether to trap focus inside the dialog when it's opened	boolean	true
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false
(escapeKeyDown) Function called when the escape key is pressed	KeyboardEvent
(exitCompleted) Function called when the animation ends in the closed state	void
(focusOutside) Function called when the focus is moved outside the component	CustomEvent<{ event?: E }>
(interactOutside) Function called when an interaction happens outside the component	\| CustomEvent<{event?: E}> \| CustomEvent<{event?: E}>
(openChanged) Fired when the dialog opens or closes.	boolean
(pointerDownOutside) Function called when the pointer is pressed down outside the component	CustomEvent<{ event?: E }>
(requestDismissed) Function called when this layer is closed due to a parent layer being closed	CustomEvent<{ originalIndex: number originalLayer: HTMLElement targetIndex: number targetLayer: HTMLElement }>

aria-label

Type

string

Description

Human-readable label for the dialog, used when the dialog title is not rendered

closeOnEscape

Type

boolean

Description

Whether to close the dialog when the escape key is pressed

closeOnInteractOutside

Type

boolean

Description

Whether to close the dialog when the outside is clicked

defaultOpen

Type

boolean

Description

The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

emphasis

Type

| 'info'
| 'success'
| 'warning'
| 'danger'
| 'neutral'

Description

The style variant of the dialog's indicator.

finalFocusEl

Type

() => HTMLElement

Description

Element to receive focus when the dialog is closed

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.

immediate

Type

boolean

Description

Whether to synchronize the present change immediately or defer it to the next frame.

initialFocusEl

Type

() => HTMLElement

Description

Element to receive focus when the dialog is opened

lazyMount

Type

boolean

Description

When true, the component will not be rendered in the DOM until it becomes visible or active.

modal

Type

boolean

Description

Whether to prevent pointer interaction outside the element and hide all content below it

open

Type

boolean

Description

The controlled open state of the dialog

persistentElements

Type

Array<
  () => Element
>

Description

The persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event

placement

Type

| 'top'
| 'center'
| 'bottom'

Description

The vertical placement of the dialog within the viewport.

'top': The dialog is positioned at the top of the viewport.
'center': The dialog is positioned at the center of the viewport.
'bottom': The dialog is positioned at the bottom of the viewport.

present

Type

boolean

Description

The controlled presence of the node.

preventScroll

Type

boolean

Description

Whether to prevent scrolling behind the dialog when it's opened

restoreFocus

Type

boolean

Description

Whether to restore focus to the element that had focus before the dialog was opened

role

Type

| 'dialog'
| 'alertdialog'

Description

The dialog's role

scrollBehavior

Type

| 'inside'
| 'outside'

Description

Defines the scroll behavior of the dialog content when modal content exceeds viewport height.

'inside': The modal and backdrop create an internal scroll area within the modal.
'outside': The modal and backdrop move with the page scroll instead of creating an internal scroll area within the modal.

size

Type

'sm' | 'md'

Description

The size of the dialog's content area and fonts. A smaller size uses less horizontal space.

skipAnimationOnMount

Type

boolean

Description

Whether to allow the initial presence animation.

trapFocus

Type

boolean

Description

Whether to trap focus inside the dialog when it's opened

unmountOnExit

Type

boolean

Description

When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.

(escapeKeyDown)

Type

KeyboardEvent

Description

Function called when the escape key is pressed

(exitCompleted)

Type

void

Description

Function called when the animation ends in the closed state

(focusOutside)

Type

CustomEvent<{
  event?: E
}>

Description

Function called when the focus is moved outside the component

(interactOutside)

Type

| CustomEvent<{event?: E}>
| CustomEvent<{event?: E}>

Description

Function called when an interaction happens outside the component

(openChanged)

Type

boolean

Description

Fired when the dialog opens or closes.

(pointerDownOutside)

Type

CustomEvent<{
  event?: E
}>

Description

Function called when the pointer is pressed down outside the component

(requestDismissed)

Type

CustomEvent<{
  originalIndex: number
  originalLayer: HTMLElement
  targetIndex: number
  targetLayer: HTMLElement
}>

Description

Function called when this layer is closed due to a parent layer being closed

<q-dialog-floating-portal>

A helper component that combines the portal, positioner, and content components.

Prop	Type
container Override the element that the portal is attached to.	\| HTMLElement \| ElementRef<HTMLElement>
disabled Set this to true to disable portalling behavior, causing the children to be rendered as-is.	boolean

container

Type

| HTMLElement
| ElementRef<HTMLElement>

Description

Override the element that the portal is attached to.

disabled

Type

boolean

Description

Set this to true to disable portalling behavior, causing the children to be rendered as-is.

q-dialog-backdrop

The backdrop that overlays the content behind the dialog.

Attribute / Property	Value
`class`	'qui-dialog__backdrop'
`data-dialog-part`	'backdrop'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean

class

Value

'qui-dialog__backdrop'

data-dialog-part

Value

'backdrop'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

q-dialog-positioner

A container for the dialog content that handles positioning.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-dialog__positioner'
`data-dialog-part`	'positioner'
`data-placement`	\| 'top' \| 'center' \| 'bottom'
`data-scroll-behavior`	\| 'inside' \| 'outside'
`data-size`	'sm' \| 'md'
`style`	CSSProperties

class

Value

'qui-dialog__positioner'

data-dialog-part

Value

'positioner'

data-placement

Value

| 'top'
| 'center'
| 'bottom'

data-scroll-behavior

Value

| 'inside'
| 'outside'

data-size

Value

'sm' | 'md'

style

Value

CSSProperties

q-dialog-content

A container for the dialog contents.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-dialog__content'
`data-dialog-part`	'content'
`data-scroll-behavior`	\| 'inside' \| 'outside'
`data-size`	'sm' \| 'md'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	-1

class

Value

'qui-dialog__content'

data-dialog-part

Value

'content'

data-scroll-behavior

Value

| 'inside'
| 'outside'

data-size

Value

'sm' | 'md'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

-1

q-dialog-body

The main content of the dialog. Container for the heading, description, indicator, and primary content of the dialog.

Prop	Type
hideIndicatorIcon Hides the indicator icon.	boolean

hideIndicatorIcon

Type

boolean

Description

Hides the indicator icon.

Attribute / Property	Value
`class`	'qui-dialog__body'
`data-dialog-part`	'body'
`data-size`	'sm' \| 'md'

q-dialog-heading

A heading that labels the dialog.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-dialog__heading'
`data-dialog-part`	'heading'
`data-size`	'sm' \| 'md'

The footer section of the dialog. Typically contains action buttons.

Attribute / Property	Value
`class`	'qui-dialog__footer'
`data-dialog-part`	'footer'
`data-size`	'sm' \| 'md'

q-dialog-indicator-icon

An icon that indicates the dialog's status.

Attribute / Property	Value
`class`	'qui-dialog__indicator-icon'
`data-emphasis`	\| 'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'
`data-size`	'sm' \| 'md'

class

Value

'qui-dialog__indicator-icon'

data-emphasis

Value

| 'info'
| 'success'
| 'warning'
| 'danger'
| 'neutral'

data-size

Value

'sm' | 'md'

q-dialog-close-button

A button that closes the dialog.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-dialog__close-button'
`data-dialog-part`	'close-trigger'

Last updated on Apr 24, 2026 by Ryan Bower

Data Grid / Table

Divider