QUI React2.6.3

Dialog

A Dialog is a component that focuses the user's attention exclusively on an information via a window that is overlaid on primary content. It is also known as a modal or modal dialog.

Overview

QUI exports 6 components to help you create any dialog:

  • QDialog: provides context and state for the dialog.
  • QDialogCloseButton: the component that closes the dialog, typically a button.
  • QDialogContent: the container for the dialog's content.
  • QDialogHeader: the header that labels the dialog.
  • QDialogBody: the container that houses the dialog's main content.
  • QDialogFooter: the footer that houses the dialog's actions.

Examples

Our dialog is based on the ARIA Dialog pattern. Accessibility is baked into the components.

  • QDialogContent has role set to dialog by default.
  • QDialogHeader provides the dialog's accessible name (aria-labelledby).
  • QDialogBody provides the dialog's accessible description (aria-describedby).

Accessibility

Showcase

import {ReactNode} from "react"


import {
  QButton,
  QDialog,
  QDialogBody,
  QDialogCloseButton,
  QDialogContent,
  QDialogFooter,
  QDialogHeader,
  QDialogTrigger,
} from "@qui/react"


export default function Showcase(): ReactNode {
  return (
    <QDialog dismissAction={<QDialogCloseButton />}>
      <QDialogTrigger>
        <QButton color="primary" variant="fill">
          Show Dialog
        </QButton>
      </QDialogTrigger>
      <QDialogContent>
        {({setOpen}) => (
          <>
            <QDialogHeader>Dialog Title</QDialogHeader>
            <QDialogBody>
              Sit nulla est ex deserunt exercitation anim occaecat. Nostrud
              ullamco deserunt aute id consequat veniam incididunt duis in sint
              irure nisi. Mollit officia cillum Lorem ullamco minim nostrud elit
              officia tempor esse quis.
            </QDialogBody>
            <QDialogFooter>
              <QButton onClick={() => setOpen(false)} variant="fill">
                Confirm
              </QButton>
            </QDialogFooter>
          </>
        )}
      </QDialogContent>
    </QDialog>
  )
}

Close Action

The dialog features a closeAction prop that you can use to render a close action. The exported QDialogCloseButton renders a clickable close icon and is typically sufficient. Should you need more customization, provide a render function to the dismissAction prop instead.

import {ReactNode} from "react"


import {
  QButton,
  QDialog,
  QDialogBody,
  QDialogCloseButton,
  QDialogContent,
  QDialogContextValue,
  QDialogHeader,
  QDialogTrigger,
} from "@qui/react"


export default function CloseElement(): ReactNode {
  return (
    <QDialog
      dismissAction={(context: QDialogContextValue) => (
        <QDialogCloseButton
          onClick={() => {
            if (window.confirm("Are you sure you want to exit?")) {
              context.setOpen(false)
            }
          }}
        />
      )}
    >
      <QDialogTrigger>
        <QButton color="primary" variant="fill">
          Show Dialog
        </QButton>
      </QDialogTrigger>
      <QDialogContent>
        <QDialogHeader>Dialog Title</QDialogHeader>
        <QDialogBody>
          Sit nulla est ex deserunt exercitation anim occaecat. Nostrud ullamco
          deserunt aute id consequat veniam incididunt duis in sint irure nisi.
          Mollit officia cillum Lorem ullamco minim nostrud elit officia tempor
          esse quis.
        </QDialogBody>
      </QDialogContent>
    </QDialog>
  )
}

Animations

Customize the enter and exit animations using the animation, animationDuration and animationEasing props.

import {ReactNode, useState} from "react"


import {
  QButton,
  QDialog,
  QDialogAnimation,
  QDialogBody,
  QDialogContent,
  QDialogFooter,
  QDialogHeader,
  QRadio,
  QRadioGroup,
  QTextInput,
} from "@qui/react"


const animations: QDialogAnimation[] = [
  "fade",
  "slide-up",
  "slide-right",
  "slide-down",
  "slide-left",
  "none",
]


export default function Animations(): ReactNode {
  const [currentAnimation, setCurrentAnimation] =
    useState<QDialogAnimation>("fade")
  const [open, setOpen] = useState(false)
  const [animationDuration, setAnimationDuration] = useState<number>(250)


  const handleChange = (animation: QDialogAnimation) => {
    setCurrentAnimation(animation)
    setOpen(true)
  }


  return (
    <div className="flex flex-col gap-6 sm:flex-row sm:items-center">
      <QRadioGroup
        className="grid justify-center gap-2"
        value={currentAnimation}
      >
        {animations.map((animation) => {
          return (
            <QRadio
              key={animation}
              label={animation}
              onClick={() => handleChange(animation)}
              value={animation}
            />
          )
        })}
      </QRadioGroup>
      <QDialog
        animation={currentAnimation}
        animationDuration={animationDuration}
        onOpenChange={(value: boolean) => {
          // respond to the emitted close events from Escape, outside click, etc...
          setOpen(value)
        }}
        open={open}
      >
        <QDialogContent>
          <QDialogHeader>Dialog Title</QDialogHeader>
          <QDialogBody>
            Sit nulla est ex deserunt exercitation anim occaecat. Nostrud
            ullamco deserunt aute id consequat veniam incididunt duis in sint
            irure nisi. Mollit officia cillum Lorem ullamco minim nostrud elit
            officia tempor esse quis.
          </QDialogBody>
          <QDialogFooter>
            <QButton onClick={() => setOpen(false)} variant="fill">
              Confirm
            </QButton>
          </QDialogFooter>
        </QDialogContent>
      </QDialog>


      <QTextInput
        className="min-w-[225px]"
        inputProps={{max: 10000, min: 0, step: 10, type: "number"}}
        label="Transition Duration (ms)"
        onChange={(event, value) => {
          setAnimationDuration(value)
        }}
        value={animationDuration}
      />
    </div>
  )
}

Height and Width

Use the fullWidth and fullHeight properties in combination with maxWidth and maxHeight to enable dialogs of any size. Here's an example of a fullscreen dialog:

import {ReactNode} from "react"


import {
  QButton,
  QDialog,
  QDialogBody,
  QDialogCloseButton,
  QDialogContent,
  QDialogFooter,
  QDialogHeader,
  QDialogTrigger,
} from "@qui/react"


export default function FullScreen(): ReactNode {
  return (
    <QDialog
      dismissAction={<QDialogCloseButton />}
      fullHeight
      fullWidth
      maxHeight="100vh"
      maxWidth="100vw"
      size="l"
    >
      <QDialogTrigger>
        <QButton color="primary" variant="fill">
          Show Dialog
        </QButton>
      </QDialogTrigger>
      <QDialogContent>
        {({setOpen}) => (
          <>
            <QDialogHeader>Dialog Title</QDialogHeader>
            <QDialogBody>
              Sit nulla est ex deserunt exercitation anim occaecat. Nostrud
              ullamco deserunt aute id consequat veniam incididunt duis in sint
              irure nisi. Mollit officia cillum Lorem ullamco minim nostrud elit
              officia tempor esse quis.
            </QDialogBody>
            <QDialogFooter>
              <QButton onClick={() => setOpen(false)} variant="fill">
                Confirm
              </QButton>
            </QDialogFooter>
          </>
        )}
      </QDialogContent>
    </QDialog>
  )
}

API

QDialog

Name & DescriptionOption(s)Default
children
*
React children prop.
ReactNode
animation
The animation to play when the dialog is entering and exiting.
| 'fade'
| 'slide-up'
| 'slide-down'
| 'slide-left'
| 'slide-right'
| 'none'
'fade'
animationDuration
The CSS transition-duration of the enter and exit animations. Supply as a number to configure both transitions at once, or supply an object to configure the enter and exit transitions independently.
| number
| {
    enter: number
    exit: number
  }
250
animationEasing
The transition timing function of the enter and exit animations. Supply as a string to configure both timings at once, or supply an object to configure the enter and exit timings independently.
| string
| {
    enter: string
    exit: string
  }
'ease'
closeOnEscape
Close the dialog when the escape key is pressed.
boolean
true
closeOnOutsideClick
Close the dialog when the user clicks the content behind it.
boolean
true
defaultOpen
The default value when uncontrolled.
boolean
disableAutoFocus
On open, the dialog focuses the first focusable element by default. Set this input to true to disable this behavior.
boolean
false
disabled
If true, the component is disabled and hidden.
boolean
false
disableScrollLock
If true, disable the scroll lock behavior.
boolean
false
dismissAction
Element to be used for the dismiss action.
| ReactElement
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactElement)
elevation
Box shadow severity of the dialog, based on the five elevation styles provided by QDS. A higher number means a more severe box shadow. Supply 0 to disable the box shadow.
| 0
| 1
| 2
| 3
| 4
| 5
| '0'
| '1'
| '2'
| '3'
| '4'
| '5'
5
fullHeight
If true, the dialog will take up the full height of its container. When this prop is true, the dialog will adapt based on maxHeight.
boolean
false
fullWidth
If true, the dialog will take up the full width of its container. When this prop is true, the dialog will adapt based on maxWidth.
boolean
false
hideBackdrop
If true, the backdrop is hidden.
boolean
false
id
Unique identifier for this dialog
string
maxHeight
Max height of the dialog.
| string
| number
'none'
maxWidth
Max width of the dialog.
| string
| number
'500px'
onOpenChange
Callback fired when panel visibility changes.
  • openThe updated state.
  • eventThe event that triggered the change.
  • reasonThe cause of the change.
(
  open: boolean,
  event?: Event,
  reason?:
    | 'ancestor-scroll'
    | 'click'
    | 'escape-key'
    | 'focus'
    | 'hover'
    | 'list-navigation'
    | 'outside-press'
    | 'reference-press'
    | 'safe-polygon',
) => void
onOutsideClick
Override the outside click event listener. If this returns false, the close action will be prevented.
  • eventthe DOM event associated with the click.
(
  event?: MouseEvent,
) => boolean
open
The controlled state for the component's visibility.
boolean
position
CSS position property of the component. Can be "absolute" or "fixed".
| 'absolute'
| 'fixed'
'absolute'
restoreFocus
v0.9.0
If true, focus will be restored to the dialog's trigger element when the dialog is closed.
boolean
true
size
Adjusts the amount of padding applied to the content container as well as font properties of the content.
| 's'
| 'm'
| 'l'
'm'
zIndex
The z-index CSS property sets the z-order of a positioned element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.
| string
| number
'var(--q-zindex-modal)'
Type
ReactNode
Description
React children prop.
Type
| 'fade'
| 'slide-up'
| 'slide-down'
| 'slide-left'
| 'slide-right'
| 'none'
Default
'fade'
Description
The animation to play when the dialog is entering and exiting.
Type
| number
| {
    enter: number
    exit: number
  }
Default
250
Description
The CSS transition-duration of the enter and exit animations. Supply as a number to configure both transitions at once, or supply an object to configure the enter and exit transitions independently.
Type
| string
| {
    enter: string
    exit: string
  }
Default
'ease'
Description
The transition timing function of the enter and exit animations. Supply as a string to configure both timings at once, or supply an object to configure the enter and exit timings independently.
Type
boolean
Default
true
Description
Close the dialog when the escape key is pressed.
Type
boolean
Default
true
Description
Close the dialog when the user clicks the content behind it.
Type
boolean
Description
The default value when uncontrolled.
Type
boolean
Default
false
Description
On open, the dialog focuses the first focusable element by default. Set this input to true to disable this behavior.
Type
boolean
Default
false
Description
If true, the component is disabled and hidden.
Type
boolean
Default
false
Description
If true, disable the scroll lock behavior.
Type
| ReactElement
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactElement)
Description
Element to be used for the dismiss action.
Type
| 0
| 1
| 2
| 3
| 4
| 5
| '0'
| '1'
| '2'
| '3'
| '4'
| '5'
Default
5
Description
Box shadow severity of the dialog, based on the five elevation styles provided by QDS. A higher number means a more severe box shadow. Supply 0 to disable the box shadow.
Type
boolean
Default
false
Description
If true, the dialog will take up the full height of its container. When this prop is true, the dialog will adapt based on maxHeight.
Type
boolean
Default
false
Description
If true, the dialog will take up the full width of its container. When this prop is true, the dialog will adapt based on maxWidth.
Type
boolean
Default
false
Description
If true, the backdrop is hidden.
Type
string
Description
Unique identifier for this dialog
Type
| string
| number
Default
'none'
Description
Max height of the dialog.
Type
| string
| number
Default
'500px'
Description
Max width of the dialog.
Type
(
  open: boolean,
  event?: Event,
  reason?:
    | 'ancestor-scroll'
    | 'click'
    | 'escape-key'
    | 'focus'
    | 'hover'
    | 'list-navigation'
    | 'outside-press'
    | 'reference-press'
    | 'safe-polygon',
) => void
Description
Callback fired when panel visibility changes.
  • openThe updated state.
  • eventThe event that triggered the change.
  • reasonThe cause of the change.
Type
(
  event?: MouseEvent,
) => boolean
Description
Override the outside click event listener. If this returns false, the close action will be prevented.
  • eventthe DOM event associated with the click.
Type
boolean
Description
The controlled state for the component's visibility.
Type
| 'absolute'
| 'fixed'
Default
'absolute'
Description
CSS position property of the component. Can be "absolute" or "fixed".
Type
boolean
Default
true
Description
If true, focus will be restored to the dialog's trigger element when the dialog is closed.
Type
| 's'
| 'm'
| 'l'
Default
'm'
Description
Adjusts the amount of padding applied to the content container as well as font properties of the content.
Type
| string
| number
Default
'var(--q-zindex-modal)'
Description
The z-index CSS property sets the z-order of a positioned element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.

QDialogContextValue

Several of the dialog's props and child elements expose the dialog's visibility as a context object. For examples of this pattern in use, refer to the Showcase and Close Action demos.

Name & DescriptionOption(s)Default
open
If true, the dialog is visible.
boolean
setOpen
Open or close the dialog using this function.
  • openthe current state of the dialog.
  • eventsthe DOM events associated with the action. May be empty.
(
  open: boolean,
  ...events: any[]
) => void
Type
boolean
Description
If true, the dialog is visible.
Type
(
  open: boolean,
  ...events: any[]
) => void
Description
Open or close the dialog using this function.
  • openthe current state of the dialog.
  • eventsthe DOM events associated with the action. May be empty.

QDialogTrigger

Name & DescriptionOption(s)Default
children
*
React children RenderProp. Can also be supplied as a function for additional functionality.
| Element
| ((
    props: RenderPropType,
  ) => Element)
Type
| Element
| ((
    props: RenderPropType,
  ) => Element)
Description
React children RenderProp. Can also be supplied as a function for additional functionality.

QDialogCloseButton

This component inherits its props from the Icon Button component.

QDialogContent

This component's children prop is a RenderProp. It accepts either a ReactNode or a function that returns a ReactNode.

When supplied as a function, the QDialogContextValue object is provided.

Refer to the above demos for examples.

Name & DescriptionOption(s)Default
children
*
RenderProp, the child of this component.
| ReactNode
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactNode)
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'section'
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
contentContainerProps
Props applied to the dialog content container.
HTMLAttributes<HTMLDivElement>
role
HTML role, applied to the root element. Don't change this unless you know what you're doing.
string
'dialog'
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
wrapperProps
Props applied to the dialog content wrapper.
HTMLAttributes<HTMLDivElement>
Type
| ReactNode
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactNode)
Description
RenderProp, the child of this component.
Type
| ElementType
| ComponentType
Default
'section'
Description
The component used for the root node. It can be a React component or element.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
HTMLAttributes<HTMLDivElement>
Description
Props applied to the dialog content container.
Type
string
Default
'dialog'
Description
HTML role, applied to the root element. Don't change this unless you know what you're doing.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.
Type
HTMLAttributes<HTMLDivElement>
Description
Props applied to the dialog content wrapper.

QDialogHeader

Name & DescriptionOption(s)Default
children
*
React children prop.
ReactNode
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'h2'
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
id
HTML id attribute. If omitted, a random value will be randomly generated for optimal accessibility.
string
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
Type
ReactNode
Description
React children prop.
Type
| ElementType
| ComponentType
Default
'h2'
Description
The component used for the root node. It can be a React component or element.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
string
Description
HTML id attribute. If omitted, a random value will be randomly generated for optimal accessibility.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.

QDialogBody

Name & DescriptionOption(s)Default
children
*
React children prop.
ReactNode
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'div'
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
id
HTML id attribute. If omitted, a random value will be randomly generated for optimal accessibility.
string
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
Type
ReactNode
Description
React children prop.
Type
| ElementType
| ComponentType
Default
'div'
Description
The component used for the root node. It can be a React component or element.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
string
Description
HTML id attribute. If omitted, a random value will be randomly generated for optimal accessibility.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.

QDialogFooter

Name & DescriptionOption(s)Default
children
*
React children prop.
ReactNode
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'div'
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
Type
ReactNode
Description
React children prop.
Type
| ElementType
| ComponentType
Default
'div'
Description
The component used for the root node. It can be a React component or element.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.
Previous
Combobox
Next
Divider
Overview
Examples
Accessibility
Showcase
Close Action
Animations
Height and Width
API
QDialog
QDialogContextValue
QDialogTrigger
QDialogCloseButton
QDialogContent
QDialogHeader
QDialogBody
QDialogFooter
Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.