Dialog (Modal)

Modal is the dialog shell; `ConfirmDialog` is built on it. ActionMenu doubles as the dropdown / menu component.

When a Modal or Drawer opens, focus goes to the first control, which is the Close button. To focus something else (the first field of a form, say), put the data-autofocus attribute on it or pass a ref as initialFocusRef.

fullScreenBelow="sm" (or "md") makes the dialog fill the screen below that breakpoint, which suits long forms on phones. With as="form", form attributes such as noValidate, autoComplete and method are passed through. initialFocusRef chooses the element focused on open.

Full screen. fullScreen makes a Modal fill the viewport at every size (no margin, border or maximum width, safe areas respected, and the page behind does not scroll): good for a file, a log or a long form. fullScreenToggle adds a button to the header that switches between the dialog and full screen, defaultFullScreen sets where it starts, and onFullScreenChange reports the switch (pass fullScreen yourself to control it).

Props

fullScreenboolean
Fill the whole viewport at every size (controlled); the page behind does not scroll.
defaultFullScreenboolean
Default: false
Start full screen when fullScreen is not set.
onFullScreenChange(fullScreen: boolean) => void
Called when the full screen button switches it.
fullScreenToggleboolean
Default: false
Add a header button that switches between the dialog and full screen.
fullScreenBelow'sm' | 'md'
Fill the screen below this breakpoint.
openboolean
Whether the dialog is shown.
onClose() => void
Called on Escape, backdrop click or the close button.
titleReactNode
Header title.
tone'default' | 'danger'
Default: 'default'
Header accent.
busyboolean
Default: false
Ignore dismissal while an action runs.
dismissibleboolean
Default: true
Set false to ignore Escape and backdrop clicks only.
rolestring
Default: 'dialog'
ARIA role (e.g. "alertdialog").
describedBystring
id of the element describing the dialog.
maxWidthstring
Default: 'max-w-lg'
Tailwind max-width class.
initialFocusRefRefObject<HTMLElement>
Element to focus on open. Without it, focus goes to an element with data-autofocus, else the first control.
asElementType
Default: 'div'
Container element; use "form" with onSubmit for a form dialog.
footerReactNode
Footer actions.
classNamestring
Default: ''
Extra classes for the root element.
childrenReactNode
Content.
...containerProps
Passed to the container element.

Modal props
Prop	Type	Default	Description
`fullScreen`	boolean	–	Fill the whole viewport at every size (controlled); the page behind does not scroll.
`defaultFullScreen`	boolean	`false`	Start full screen when `fullScreen` is not set.
`onFullScreenChange`	(fullScreen: boolean) => void	–	Called when the full screen button switches it.
`fullScreenToggle`	boolean	`false`	Add a header button that switches between the dialog and full screen.
`fullScreenBelow`	'sm' \| 'md'	–	Fill the screen below this breakpoint.
`open`	boolean	–	Whether the dialog is shown.
`onClose`	() => void	–	Called on Escape, backdrop click or the close button.
`title`	ReactNode	–	Header title.
`tone`	'default' \| 'danger'	`'default'`	Header accent.
`busy`	boolean	`false`	Ignore dismissal while an action runs.
`dismissible`	boolean	`true`	Set false to ignore Escape and backdrop clicks only.
`role`	string	`'dialog'`	ARIA role (e.g. "alertdialog").
`describedBy`	string	–	id of the element describing the dialog.
`maxWidth`	string	`'max-w-lg'`	Tailwind max-width class.
`initialFocusRef`	RefObject<HTMLElement>	–	Element to focus on open. Without it, focus goes to an element with `data-autofocus`, else the first control.
`as`	ElementType	`'div'`	Container element; use "form" with `onSubmit` for a form dialog.
`footer`	ReactNode	–	Footer actions.
`className`	string	`''`	Extra classes for the root element.
`children`	ReactNode	–	Content.
`...containerProps`		–	Passed to the container element.

Related hooks and theme:useDialogFocus useEscapeKey