Dialog

Installation

npx @park-ui/cli add dialog

Add Component

Copy the code snippet below into you components folder.

'use client'
import { Dialog, useDialogContext } from '@ark-ui/react/dialog'
import { ark } from '@ark-ui/react/factory'
import { type ComponentProps, forwardRef } from 'react'
import { createStyleContext, styled } from 'styled-system/jsx'
import { dialog } from 'styled-system/recipes'

const { withRootProvider, withContext } = createStyleContext(dialog)

export type RootProps = ComponentProps<typeof Root>
export const Root = withRootProvider(Dialog.Root, {
  defaultProps: { unmountOnExit: true, lazyMount: true },
})
export const RootProvider = withRootProvider(Dialog.RootProvider, {
  defaultProps: { unmountOnExit: true, lazyMount: true },
})
export const Backdrop = withContext(Dialog.Backdrop, 'backdrop')
export const CloseTrigger = withContext(Dialog.CloseTrigger, 'closeTrigger')
export const Content = withContext(Dialog.Content, 'content')
export const Description = withContext(Dialog.Description, 'description')
export const Positioner = withContext(Dialog.Positioner, 'positioner')
export const Title = withContext(Dialog.Title, 'title')
export const Trigger = withContext(Dialog.Trigger, 'trigger')
export const Body = withContext(ark.div, 'body')
export const Header = withContext(ark.div, 'header')
export const Footer = withContext(ark.div, 'footer')

const StyledButton = styled(ark.button)

export const ActionTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeof StyledButton>>(
  function ActionTrigger(props, ref) {
    const dialog = useDialogContext()
    return <StyledButton {...props} ref={ref} onClick={() => dialog.setOpen(false)} />
  },
)

export { DialogContext as Context } from '@ark-ui/react/dialog'

Integrate Recipe

Integrate this recipe in to your Panda config.

import { dialogAnatomy } from '@ark-ui/react/dialog'
import { defineSlotRecipe } from '@pandacss/dev'

export const dialog = defineSlotRecipe({
  className: 'dialog',
  slots: dialogAnatomy.extendWith('header', 'body', 'footer').keys(),
  base: {
    backdrop: {
      background: 'black.a7',
      height: '100dvh',
      left: '0',
      position: 'fixed',
      top: '0',
      width: '100dvw',
      zIndex: 'var(--z-index)',
      _open: {
        animationName: 'fade-in',
        animationTimingFunction: 'emphasized-in',
        animationDuration: 'normal',
      },
      _closed: {
        animationName: 'fade-out',
        animationTimingFunction: 'emphasized-out',
        animationDuration: 'fast',
      },
    },
    positioner: {
      '--dialog-z-index': 'zIndex.modal',
      display: 'flex',
      height: '100dvh',
      justifyContent: 'center',
      left: 0,
      overscrollBehaviorY: 'none',
      position: 'fixed',
      top: 0,
      width: '100dvw',
      zIndex: 'calc(var(--dialog-z-index) + var(--layer-index, 0))',
    },

    title: {
      fontWeight: 'semibold',
      textStyle: 'lg',
    },
    description: {
      color: 'fg.muted',
      textStyle: 'sm',
    },
    closeTrigger: {
      pos: 'absolute',
      top: '3',
      insetEnd: '3',
    },
    content: {
      '--dialog-z-index': 'zIndex.modal',
      bg: 'gray.surface.bg',
      borderRadius: 'l3',
      boxShadow: 'lg',
      display: 'flex',
      flexDirection: 'column',
      my: 'var(--dialog-margin, var(--dialog-base-margin))',
      outline: 0,
      position: 'relative',
      textStyle: 'sm',
      width: '100%',
      zIndex: 'calc(var(--dialog-z-index) + var(--layer-index, 0))',
      py: { base: '4', md: '6' },
      gap: { base: '4', md: '6' },
      _open: {
        animationDuration: 'slowest',
      },
      _closed: {
        animationDuration: 'normal',
      },
    },
    header: {
      display: 'flex',
      flexDirection: 'column',
      gap: '0.5',
      px: { base: '4', md: '6' },
      flex: '0',
    },
    body: {
      display: 'flex',
      flex: '1',
      flexDirection: 'column',
      alignItems: 'flex-start',
      px: { base: '4', md: '6' },
    },
    footer: {
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'flex-end',
      flex: '0',
      gap: '3',
      px: { base: '4', md: '6' },
    },
  },
  defaultVariants: {
    size: 'md',
    scrollBehavior: 'outside',
    placement: 'center',
    motionPreset: 'scale',
  },
  variants: {
    motionPreset: {
      scale: {
        content: {
          _open: { animationName: 'scale-in, fade-in' },
          _closed: { animationName: 'scale-out, fade-out' },
        },
      },
      'slide-in-bottom': {
        content: {
          _open: { animationName: 'slide-from-bottom, fade-in' },
          _closed: { animationName: 'slide-to-bottom, fade-out' },
        },
      },
      'slide-in-top': {
        content: {
          _open: { animationName: 'slide-from-top, fade-in' },
          _closed: { animationName: 'slide-to-top, fade-out' },
        },
      },
      'slide-in-left': {
        content: {
          _open: { animationName: 'slide-from-left, fade-in' },
          _closed: { animationName: 'slide-to-left, fade-out' },
        },
      },
      'slide-in-right': {
        content: {
          _open: { animationName: 'slide-from-right, fade-in' },
          _closed: { animationName: 'slide-to-right, fade-out' },
        },
      },
      none: {},
    },
    size: {
      xs: { content: { maxW: 'xs' } },
      sm: { content: { maxW: 'sm' } },
      md: { content: { maxW: 'md' } },
      lg: { content: { maxW: 'lg' } },
      xl: { content: { maxW: 'xl' } },
      cover: {
        positioner: { padding: '8' },
        content: {
          width: '100%',
          height: '100%',
          '--dialog-margin': '0',
        },
      },
      full: {
        content: {
          maxW: '100dvw',
          minH: '100dvh',
          '--dialog-margin': '0',
          borderRadius: '0',
        },
      },
    },
    placement: {
      center: {
        positioner: {
          alignItems: 'center',
        },
        content: {
          '--dialog-base-margin': 'auto',
          mx: 'auto',
        },
      },
      top: {
        positioner: {
          alignItems: 'flex-start',
        },
        content: {
          '--dialog-base-margin': 'spacing.16',
          mx: 'auto',
        },
      },
      bottom: {
        positioner: {
          alignItems: 'flex-end',
        },
        content: {
          '--dialog-base-margin': 'spacing.16',
          mx: 'auto',
        },
      },
    },
    scrollBehavior: {
      inside: {
        positioner: {
          overflow: 'hidden',
        },
        content: {
          maxH: 'calc(100% - 7.5rem)',
        },
        body: {
          overflow: 'auto',
        },
      },
      outside: {
        positioner: {
          overflow: 'auto',
          pointerEvents: 'auto',
        },
      },
    },
  },
})

Usage

import { Dialog } from '@/components/ui'

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.CloseTrigger />
      <Dialog.Header>
        <Dialog.Title />
        <Dialog.Description />
      </Dialog.Header>
      <Dialog.Body />
      <Dialog.Footer>
        <Dialog.ActionTrigger />
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

Examples

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.

Responsive Size

Use responsive values for the size prop to make the dialog adapt to different screen sizes. We recommend using exact breakpoints values instead of using a base to ensure styles are properly contained.

Placements

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.

'use client'
import { Portal } from '@ark-ui/react/portal'
import { useState } from 'react'
import { Button, CloseButton, Dialog } from '@/components/ui'

export const App = () => {
  const [open, setOpen] = useState(false)

  return (
    <Dialog.Root open={open} onOpenChange={(e) => setOpen(e.open)}>
      <Dialog.Trigger asChild>
        <Button variant="outline">Open Dialog</Button>
      </Dialog.Trigger>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            <Dialog.Header>
              <Dialog.Title>Title</Dialog.Title>
              <Dialog.Description>Description</Dialog.Description>
            </Dialog.Header>
            <Dialog.Body>{/* Content */}</Dialog.Body>
            <Dialog.Footer>
              <Dialog.ActionTrigger asChild>
                <Button variant="outline">Cancel</Button>
              </Dialog.ActionTrigger>
              <Dialog.ActionTrigger asChild>
                <Button>Save</Button>
              </Dialog.ActionTrigger>
            </Dialog.Footer>
            <Dialog.CloseTrigger asChild>
              <CloseButton />
            </Dialog.CloseTrigger>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

Nested Dialogs

You can nest dialogs by using the Dialog.Root component inside another Dialog.Root component.

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.

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

Props

Root

Prop	Default	Type
`motionPreset`	`'scale'`	`'scale' \| 'slide-in-bottom' \| 'slide-in-top' \| 'slide-in-left' \| 'slide-in-right' \| 'none'`
`size`	`'md'`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'cover' \| 'full'`
`placement`	`'center'`	`'center' \| 'top' \| 'bottom'`
`scrollBehavior`	`'outside'`	`'inside' \| 'outside'`
`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
`defaultOpen`	`false`	`boolean` The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.
`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
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`trapFocus`	`true`	`boolean` Whether to trap focus inside the dialog when it's opened
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.
`aria-label`		`string` Human readable label for the dialog, in event the dialog title is not rendered
`finalFocusEl`		`() => MaybeElement` 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`		`() => MaybeElement` Element to receive focus when the dialog is opened
`onEscapeKeyDown`		`(event: KeyboardEvent) => void` Function called when the escape key is pressed
`onExitComplete`		`VoidFunction` 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` Function to call when the dialog's open state changes
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onRequestDismiss`		`(event: LayerDismissEvent) => void` Function called when this layer is closed due to a parent layer being closed
`open`		`boolean` The controlled open state of the dialog
`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