Dialog
View as MarkdownA popup that opens on top of the entire page.
Features
Permalink to heading "Features"- Focus is trapped within the dialog and restored when closed
- Supports modal and non-modal modes
- Page scrolling is locked while a modal dialog is open
- Pressing
Escapecloses the dialog - Opens from a trigger,
defaultOpenor your own code
<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>
Installation
Permalink to heading "Installation"typo3 ui:add dialog
Please copy the files manually from GitHub into your project.
Read more about installing Components and Primitives.
Examples
Permalink to heading "Examples"Confirm a destructive action
Permalink to heading "Confirm a destructive action"Set role="alertdialog" and closeOnInteractOutside="{false}" with closeOnEscape="{false}" for critical confirmations like deleting an item. The Cancel button receives focus when the dialog opens, so the safest action comes first.
Open a dialog from a dialog
Permalink to heading "Open a dialog from a dialog"Put a dialog.root inside the content of another dialog. Each level opens on top of the previous one.
Add a popover to a dialog
Permalink to heading "Add a popover to a dialog"Use a popover for small anchored extras like share options. The dialog keeps its focus management.
Scroll the whole dialog
Permalink to heading "Scroll the whole dialog"When the content is taller than the viewport, the dialog scrolls as one piece, header and footer included. The dialog.positioner is the scroll container.
Scroll the dialog body
Permalink to heading "Scroll the dialog body"Keep the header and footer in view while the body scrolls: set a max-height on the dialog content and overflow-y: auto on the body.
Keep it open on outside click
Permalink to heading "Keep it open on outside click"Set closeOnInteractOutside="{false}" for a dialog the visitor should answer, like a cookie settings dialog. A click on the backdrop leaves it open.
Keep it open on Escape
Permalink to heading "Keep it open on Escape"Set closeOnEscape="{false}" to ignore the Escape key.
API Reference
Permalink to heading "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
Permalink to heading "dialog.root"Provides dialog state and context for the composed parts. Renders no wrapper element.
| Name | Description | Required | Default |
|---|---|---|---|
trapFocus | booleanWhether to trap focus inside the dialog when it's opened. | No | true |
preventScroll | booleanWhether to prevent scrolling behind the dialog when it's opened. | No | true |
modal | booleanWhether to prevent pointer interaction outside the element and hide all content below it. | No | true |
restoreFocus | booleanWhether to restore focus to the element that had focus before the dialog was opened. | No | true |
closeOnInteractOutside | booleanWhether to close the dialog when the outside is clicked. | No | true |
closeOnEscape | booleanWhether to close the dialog when the escape key is pressed. | No | true |
role | Enum\DialogRoleThe dialog's role. | No | Dialog |
defaultOpen | booleanThe initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog. | No | false |
rootId | stringThe root ID of the component, used for hydration and identification. | No | - |
ids | arrayThe IDs of of the component parts for composition. | No | [] |
autoMount | booleanWhether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` | No | true |
dialog.trigger
Permalink to heading "dialog.trigger"Opens the dialog. Renders a <button> element.
| Name | Description | Required | Default |
|---|---|---|---|
value | string | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-dialog-trigger | <uid> |
data-value | The value of the item |
data-state | "open" | "closed" |
data-current | Present when current |
dialog.backdrop
Permalink to heading "dialog.backdrop"Displays the overlay behind the dialog content. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-dialog-backdrop | <uid> |
data-state | "open" | "closed" |
data-nested | Present when the backdrop is nested within another {{widget}} |
data-has-nested | Present when the backdrop has nested {{widget}}s |
dialog.positioner
Permalink to heading "dialog.positioner"Positions the dialog content within the viewport. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-dialog-positioner | <uid> |
data-nested | Present when the positioner is nested within another {{widget}} |
data-has-nested | Present when the positioner has nested {{widget}}s |
dialog.content
Permalink to heading "dialog.content"Contains the dialog surface and interactive content. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-dialog-content | <uid> |
data-state | "open" | "closed" |
data-nested | dialog |
data-has-nested | dialog |
dialog.title
Permalink to heading "dialog.title"Provides the accessible title for the dialog. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
dialog.description
Permalink to heading "dialog.description"Provides supporting descriptive text for the dialog. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
dialog.closeTrigger
Permalink to heading "dialog.closeTrigger"Closes the dialog when activated. Renders a <button> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Machine JavaScript API
Permalink to heading "Machine JavaScript API"| Name | Type | Description |
|---|---|---|
open | boolean | Whether the dialog is open |
setOpen | (open: boolean) => void | Function to open or close the dialog |
triggerValue | string | null | The active trigger value |
setTriggerValue | (value: string | null) => void | Function to set the active trigger value |
getTriggerState | (props?: TriggerProps) => TriggerState | Returns the state of a specific trigger, including whether it's the currently active one |
getBackdropState | () => BackdropState | Returns the state of the backdrop |
getPositionerState | () => PositionerState | Returns the state of the positioner |
getContentState | () => ContentState | Returns the state of the content |
Accessibility
Permalink to heading "Accessibility"| Key | Description |
|---|---|
Enter | When focus is on the trigger, opens the dialog. |
Tab | Moves focus to the next focusable element within the content. Focus is trapped within the dialog. |
Shift + Tab | Moves focus to the previous focusable element. Focus is trapped within the dialog. |
Esc | Closes the dialog and moves focus to trigger or the defined final focus element |