Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsPlaygroundGuidesBlog
Sponsor

Dialog

Used to display a dialog prompt

SourceStorybookRecipeArk

Usage

import { Dialog } from "@chakra-ui/react"
<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.CloseTrigger />
      <Dialog.Header>
        <Dialog.Title />
      </Dialog.Header>
      <Dialog.Body />
      <Dialog.Footer />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

Examples

Sizes

Use the size prop to change the size of the dialog component.

Cover

Use the size="cover" prop to make the dialog component cover the entire screen while revealing a small portion of the page behind.

Fullscreen

Use the size="full" prop to make the dialog component take up the entire screen.

Placement

Use the placement prop to change the placement of the dialog component.

Controlled

Use the open and onOpenChange prop to control the visibility of the dialog component.

Store

An alternative way to control the dialog is to use the RootProvider component and the useDialog store hook.

This way you can access the dialog state and methods from outside the dialog.

Context

Use the DialogContext component to access the dialog state and methods from outside the dialog.

Initial Focus

Use the initialFocusEl prop to set the initial focus of the dialog component.

Inside Scroll

Use the scrollBehavior=inside prop to change the scroll behavior of the dialog when its content overflows.

Outside Scroll

Use the scrollBehavior=outside prop to change the scroll behavior of the dialog when its content overflows.

Motion Preset

Use the motionPreset prop to change the animation of the dialog component.

Alert Dialog

Set the role: "alertdialog" prop to change the dialog component to an alert dialog.

Close Button Outside

Here's an example of how to customize the Dialog.CloseTrigger component to position the close button outside the dialog component.

Non-Modal Dialog

We don't recommend using a non-modal dialog due to the accessibility concerns they present. In event you need it, here's what you can do:

  • set the modal prop to false
  • set pointerEvents to none on the Dialog.Positioner component
  • (optional)set the closeOnInteractOutside prop to false

DataList

Here's an example of how to compose the dialog component with the DataList component.

Props

Root

PropDefaultType
closeOnEscape true
boolean

Whether to close the dialog when the escape key is pressed

closeOnInteractOutside true
boolean

Whether to close the dialog when the outside is clicked

lazyMount false
boolean

Whether to enable lazy mounting

modal true
boolean

Whether to prevent pointer interaction outside the element and hide all content below it

preventScroll true
boolean

Whether to prevent scrolling behind the dialog when it's opened

role '\'dialog\''
'dialog' | 'alertdialog'

The dialog's role

trapFocus true
boolean

Whether to trap focus inside the dialog when it's opened

unmountOnExit false
boolean

Whether to unmount on exit.

colorPalette 'gray'
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

placement 'top'
'center' | 'top' | 'bottom'

The placement of the component

scrollBehavior 'outside'
'inside' | 'outside'

The scrollBehavior of the component

size 'md'
'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'cover' | 'full'

The size of the component

motionPreset 'scale'
'scale' | 'slide-in-bottom' | 'slide-in-top' | 'slide-in-left' | 'slide-in-right' | 'none'

The motionPreset of the component

aria-label
string

Human readable label for the dialog, in event the dialog title is not rendered

defaultOpen
boolean

The initial open state of the dialog when it is first rendered. Use when you do not need to control its open state.

finalFocusEl
() => HTMLElement | null

Element to receive focus when the dialog is closed

id
string

The unique identifier of the machine.

ids
Partial<{ trigger: string positioner: string backdrop: string content: string closeTrigger: string title: string description: string }>

The ids of the elements in the dialog. Useful for composition.

immediate
boolean

Whether to synchronize the present change immediately or defer it to the next frame

initialFocusEl
() => HTMLElement | null

Element to receive focus when the dialog is opened

onEscapeKeyDown
(event: KeyboardEvent) => void

Function called when the escape key is pressed

onExitComplete
() => void

Function called when the animation ends in the closed state

onFocusOutside
(event: FocusOutsideEvent) => void

Function called when the focus is moved outside the component

onInteractOutside
(event: InteractOutsideEvent) => void

Function called when an interaction happens outside the component

onOpenChange
(details: OpenChangeDetails) => void

Callback to be invoked when the dialog is opened or closed

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

Function called when the pointer is pressed down outside the component

open
boolean

Whether the dialog is open

persistentElements
(() => Element | null)[]

Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event

present
boolean

Whether the node is present (controlled by the user)

restoreFocus
boolean

Whether to restore focus to the element that had focus before the dialog was opened

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

Previous

Data List

Next

Drawer