Skip to main content

Dialog

View as Markdown

A popup that opens on top of the entire page.

View Sourcefor Dialog componentZag.js Docsfor Dialog component

Features

Installation

typo3 ui:add dialog

Read more about installing Components and Primitives.

Examples

Alert Dialog

For critical confirmations or destructive actions, use role="alertdialog". Alert dialogs differ from regular dialogs in important ways:

Nested Dialogs

Open a dialog from within another dialog.

Popover Inside Dialog

Render a popover inside dialog content when you need anchored secondary actions without breaking dialog focus management.

Scrollable Outside

The dialog positioner can scroll when the content exceeds the viewport height, so the entire dialog can scroll together.

Scrollable Inside

With some additions, the dialog content can scroll when it exceeds the viewport height, while keeping the header and footer visible. Set a max-height on the content and use overflow-y: auto to enable scrolling inside the dialog's content area.

Prevent Close on Outside Click

Keep the dialog open when clicking outside.

Prevent Close on Escape

Disable closing the dialog with the Escape key.

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

dialog.root

Provides dialog state and context for the composed parts. Renders no wrapper element.

NameDescriptionRequiredDefault
trapFocusboolean
Whether to trap focus inside the dialog when it's opened. 		No 
true
preventScrollboolean
Whether to prevent scrolling behind the dialog when it's opened. 		No 
true
modalboolean
Whether to prevent pointer interaction outside the element and hide all content below it. 		No 
true
restoreFocusboolean
Whether to restore focus to the element that had focus before the dialog was opened. 		No 
true
closeOnInteractOutsideboolean
Whether to close the dialog when the outside is clicked. 		No 
true
closeOnEscapeboolean
Whether to close the dialog when the escape key is pressed. 		No 
true
rolestring
The dialog's role. 		No 
'dialog'
defaultOpenboolean
The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog. 		No 
false
rootIdstring
The root ID of the component, used for hydration and identification. 		No 
-
idsarray
The IDs of of the component parts for composition. 		No 
[]
controlledboolean
If true, the component is meant to be initialized manually inside another component 		No 
false

dialog.trigger

Opens the dialog. Renders a <button> element.

NameDescriptionRequiredDefault
valuestring
No 
-
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

Rendered data attributes

AttributeDescription
data-scopedialog
data-parttrigger
data-valueThe value of the item
data-state"open" | "closed"
data-currentPresent when current

dialog.backdrop

Displays the overlay behind the dialog content. Renders a <div> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

Rendered data attributes

AttributeDescription
data-scopedialog
data-partbackdrop
data-state"open" | "closed"

dialog.positioner

Positions the dialog content within the viewport. Renders a <div> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

dialog.content

Contains the dialog surface and interactive content. Renders a <div> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

Rendered data attributes

AttributeDescription
data-scopedialog
data-partcontent
data-state"open" | "closed"
data-nesteddialog
data-has-nesteddialog

dialog.title

Provides the accessible title for the dialog. Renders a <div> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

dialog.description

Provides supporting descriptive text for the dialog. Renders a <div> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

dialog.closeTrigger

Closes the dialog when activated. Renders a <button> element.

NameDescriptionRequiredDefault
asChildboolean
If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. 		No 
-
classstring
The CSS class(es) to be applied to the component. 		No 
-
attributesarray
Additional attributes that should be rendered on the component where ui:attributes is used. 		No 
[]

Machine JavaScript API

NameTypeDescription
openbooleanWhether the dialog is open
setOpen(open: boolean) => voidFunction to open or close the dialog
triggerValuestring | nullThe active trigger value
setTriggerValue(value: string | null) => voidFunction to set the active trigger value

Accessibility

KeyDescription
EnterWhen focus is on the trigger, opens the dialog.
TabMoves focus to the next focusable element within the content. Focus is trapped within the dialog.
Shift + TabMoves focus to the previous focusable element. Focus is trapped within the dialog.
EscCloses the dialog and moves focus to trigger or the defined final focus element

Anatomy

<primitives:dialog.root>
    <primitives:dialog.trigger />
    <primitives:dialog.backdrop />
    <primitives:dialog.positioner>
        <primitives:dialog.content>
            <primitives:dialog.title />
            <primitives:dialog.description />
        </primitives:dialog.content>
    </primitives:dialog.positioner>
</primitives:dialog.root>