ts
| Guidance | Practices |
|---|---|
| Do | Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond. |
| Do | Include a clear title in the header so users immediately understand what the dialog is asking. |
| Do | Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop. |
| Do | Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead. |
| Don't | Use a dialog for simple messages that could be shown inline or as a toast notification. |
| Don't | Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead. |
| Don't | Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms. |
| Prop | Type | Description |
|---|---|---|
isOpenrequired | boolean | Whether the dialog is open (required). |
onOpenChangerequired | (isOpen: boolean) => unknown | Callback when dialog visibility changes (required). |
childrenrequired | ReactNode | Dialog content. |
width | number | string (default: 400) | Width of the dialog in pixels or any CSS value. |
maxHeight | number | string (default: '75vh') | Maximum height of the dialog. |
position | XDSDialogPosition | Static position for the dialog; centered by default when omitted. |
variant | 'standard' | 'fullscreen' (default: 'standard') | Dialog variant — fullscreen expands to fill the entire viewport. |
purpose | 'required' | 'form' | 'info' (default: 'info') | Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both. |
isInline | boolean (default: false) | Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only. |
| Prop | Type | Description |
|---|---|---|
title | string | Dialog title (receives focus on open). |
subtitle | string | Subtitle below the title. |
onOpenChange | (isOpen: boolean) => unknown | Close button callback (no button if omitted). |
startContent | ReactNode | Content before the title (e.g., a back button). |
endContent | ReactNode | Content after the title, before close button. |
hasDivider | boolean (default: true) | Adds border at the bottom edge. |
| Prop | Type | Description |
|---|---|---|
show | (content: ReactNode, options?: DialogOptions) => void | Show the dialog with the given content. Options are the same as XDSDialog props minus isOpen/onOpenChange/children. |
hide | () => void | Hide the dialog. |
isOpen | boolean | Whether the dialog is currently open. |
element | ReactNode | The dialog element — render this in your JSX tree. |