Dialog
Material 3 dialog surface, content hierarchy, actions, scrim, dismissal, and browser modal semantics.
Dialogs interrupt the current flow to present focused information or request a decision. Use them for short, high-priority interactions that benefit from modal attention rather than as general page containers.
When to use
Use a dialog when users must focus on a concise decision, confirmation, or short task before returning to the underlying flow. Prefer inline content, sheets, or full pages for longer tasks that do not need modal interruption.
Composition
The public primitives keep Material presentation and browser modal responsibilities explicit:
DialogTriggerowns trigger/open state and focus restoration;DialogOverlayowns portal placement, modal underlay, Material scrim, outside/Escape dismissal policy, and browser focus containment;Dialogowns the Material container and dialog semantics;- title/description/icon/action primitives compose the Material content hierarchy.
Actions
Keep action sets concise and directly related to the dialog decision. DialogAction performs an action without implicit close behavior; DialogCloseAction uses the close slot when activation should dismiss the dialog.
<DialogActions>
<DialogCloseAction>Cancel</DialogCloseAction>
<DialogAction onPress={save}>Save</DialogAction>
</DialogActions>Dismissal and modal behavior
DialogOverlay is dismissable by default. React Aria owns Escape/outside dismissal, modal focus containment, scroll interaction policy, and focus restoration. Set non-dismissable behavior only when the task genuinely requires an explicit action path.
The Material scrim is presentation inside the overlay contract. It is not a second modal/focus manager.
Accessibility
Use DialogTitle and, when useful, DialogDescription so the dialog has a clear accessible name and supporting relationship. Keep focusable content purposeful and ensure a non-dismissable dialog always offers a reachable way to complete or cancel the task.
Do not manually add a second focus trap or Escape handler around DialogOverlay; competing modal managers can break restoration and keyboard interaction.
API reference
Dialog
Dialog({ containerColor, headlineColor, supportingTextColor, iconColor, actionColor, shape, shadowColor, className, style, ...props }: DialogProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
actionColor | Property.Color | undefined | — | — | @m3-ui/ui |
containerColor | Property.BackgroundColor | undefined | — | — | @m3-ui/ui |
headlineColor | Property.Color | undefined | — | — | @m3-ui/ui |
iconColor | Property.Color | undefined | — | — | @m3-ui/ui |
shadowColor | Property.Color | undefined | — | — | @m3-ui/ui |
shape | Property.BorderRadius<string | number> | undefined | — | — | @m3-ui/ui |
style | CSSProperties | undefined | — | — | @m3-ui/ui |
supportingTextColor | Property.Color | undefined | — | — | @m3-ui/ui |
Inherited React / web props (81)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
children | React.ReactNode | ((opts: DialogRenderProps) => ReactNode) | — | Children of the dialog. A function may be provided to access a function to close the dialog. | react-aria-components |
className | string | undefined | 'react-aria-Dialog' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. | react-aria-components |
dir | string | undefined | — | — | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
key | Key | null | undefined | — | — | @types/react |
lang | string | undefined | — | — | @react-types/shared |
onAnimationEnd | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onClick | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLElement> | undefined | — | — | @react-types/shared |
ref | Ref<HTMLElement> | undefined | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). | @types/react |
render | DOMRenderFunction<"section", undefined> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
role | "alertdialog" | "dialog" | undefined | 'dialog' | The accessibility role for the dialog. | react-aria |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
Source: packages/ui/src/components/Dialog/Dialog.tsx:70
Material fidelity and web adaptation
- Family
- Dialogs
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- Material dialog surface, headline, supporting text, icon, and actions
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implemented as Material dialog primitives for scrim, container surface, title, description, icon, and actions, with theme-aware portal placement.
- Behavior fidelity
- adapted: React Aria owns modal focus scope, focus restoration, Escape handling, outside dismissal, portal behavior, and accessible dialog relationships. Material styling is layered on those native web interaction semantics.
- Semantics fidelity
- adapted: React Aria owns modal focus scope, focus restoration, Escape handling, outside dismissal, portal behavior, and accessible dialog relationships. Material styling is layered on those native web interaction semantics.
- Adaptations
- React Aria owns modal focus scope, focus restoration, Escape handling, outside dismissal, portal behavior, and accessible dialog relationships. Material styling is layered on those native web interaction semantics.
Material supplies surface, scrim, typography, hierarchy, shape, and action presentation. React Aria's modal/dialog/portal model supplies browser focus containment, dismissal, and restoration rather than mechanically recreating Compose runtime behavior.
Related components
- Bottom sheets — modal or non-modal bottom-anchored surfaces.
- Scrim — lower-level obscuring/dismiss layer without modal lifecycle ownership.