Dialog | Ark UI

Anatomy

To use the dialog component correctly, you’ll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Dialog component in your project. Let’s take a look at the most basic example

import { Dialog, Portal } from '@ark-ui/react'

const Basic = () => (
  <Dialog.Root>
    <Dialog.Trigger>Open Dialog</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
)

import { Dialog } from '@ark-ui/solid'
import { Portal } from 'solid-js/web'

const Basic = () => {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open Dialog</Dialog.Trigger>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            <Dialog.Title>Dialog Title</Dialog.Title>
            <Dialog.Description>Dialog Description</Dialog.Description>
            <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

<script setup lang="ts">
import { Teleport, ref } from 'vue'
import { Dialog } from '@ark-ui/vue'

const open = ref(false)
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger>Open Dialog</Dialog.Trigger>
    <Teleport to="body">
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Teleport>
  </Dialog.Root>
</template>

Controlled Dialog

To create a controlled Dialog component, manage the state of the dialog using the open and onOpenChange props:

import { Dialog, Portal } from '@ark-ui/react'
import { useState } from 'react'

const Controlled = () => {
  const [isOpen, setIsOpen] = useState(false)
  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Dialog</button>
      <Dialog.Root open={isOpen} onOpenChange={(e) => setIsOpen(e.open)}>
        <Portal>
          <Dialog.Backdrop />
          <Dialog.Positioner>
            <Dialog.Content>
              <Dialog.Title>Dialog Title</Dialog.Title>
              <Dialog.Description>Dialog Description</Dialog.Description>
              <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
            </Dialog.Content>
          </Dialog.Positioner>
        </Portal>
      </Dialog.Root>
    </>
  )
}

import { Dialog } from '@ark-ui/solid'
import { createSignal } from 'solid-js'
import { Portal } from 'solid-js/web'

const Controlled = () => {
  const [isOpen, setIsOpen] = createSignal(false)

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Dialog</button>
      <Dialog.Root open={isOpen()} onOpenChange={() => setIsOpen(false)}>
        <Portal>
          <Dialog.Backdrop />
          <Dialog.Positioner>
            <Dialog.Content>
              <Dialog.Title>Dialog Title</Dialog.Title>
              <Dialog.Description>Dialog Description</Dialog.Description>
              <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
            </Dialog.Content>
          </Dialog.Positioner>
        </Portal>
      </Dialog.Root>
    </>
  )
}

<script setup lang="ts">
import { Teleport, ref } from 'vue'
import { Dialog } from '@ark-ui/vue'

const open = ref(false)
</script>

<template>
  <button @click="() => (open = true)">Open Dialog</button>
  <Dialog.Root v-model="open">
    <Teleport to="body">
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Teleport>
  </Dialog.Root>
</template>

Lazy Mounting

Lazy mounting is a feature that allows the content of a dialog to be rendered only when the dialog is first opened. This is useful for performance optimization, especially when dialog content is large or complex. To enable lazy mounting, use the lazyMount prop on the Dialog.Root component.

In addition, the unmountOnExit prop can be used in conjunction with lazyMount to unmount the dialog content when the Dialog is closed, freeing up resources. The next time the dialog is activated, its content will be re-rendered.

import { Dialog, Portal } from '@ark-ui/react'

const LazyMount = () => (
  <Dialog.Root lazyMount unmountOnExit onExitComplete={() => console.log('onExitComplete invoked')}>
    <Dialog.Trigger>Open Dialog</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
)

import { Dialog } from '@ark-ui/solid'

const LazyMount = () => {
  return (
    <Dialog.Root lazyMount unmountOnExit>
      <Dialog.Trigger>Open Dialog</Dialog.Trigger>
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Dialog.Root>
  )
}

<script setup lang="ts">
import { Teleport, ref } from 'vue'
import { Dialog } from '@ark-ui/vue'

const open = ref(false)
</script>

<template>
  <Dialog.Root lazyMount unmountOnExit @exit-complete="() => console.log('onExitComplete invoked')">
    <Dialog.Trigger>Open Dialog</Dialog.Trigger>
    <Teleport to="body">
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Teleport>
  </Dialog.Root>
</template>

Using Render Function

The Dialog component supports the use of a render function as a child for more control. This allows access to dialog states like isOpen:

import { Dialog, Portal } from '@ark-ui/react'

const RenderFn = () => (
  <Dialog.Root>
    {({ isOpen }) => (
      <>
        <Dialog.Trigger>Open Dialog</Dialog.Trigger>
        <Portal>
          <Dialog.Backdrop />
          <Dialog.Positioner>
            <Dialog.Content>
              <Dialog.Title>Dialog Title</Dialog.Title>
              <Dialog.Description>Dialog Description</Dialog.Description>
              <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
            </Dialog.Content>
          </Dialog.Positioner>
        </Portal>
        <p>Dialog is {isOpen ? 'open' : 'closed'}</p>
      </>
    )}
  </Dialog.Root>
)

import { Dialog } from '@ark-ui/solid'
import { Portal } from 'solid-js/web'

const RenderFn = () => {
  return (
    <Dialog.Root>
      {(api) => (
        <>
          <Dialog.Trigger>Open Dialog</Dialog.Trigger>
          <Portal>
            <Dialog.Backdrop />
            <Dialog.Positioner>
              <Dialog.Content>
                <Dialog.Title>Dialog Title</Dialog.Title>
                <Dialog.Description>Dialog Description</Dialog.Description>
                <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
              </Dialog.Content>
            </Dialog.Positioner>
          </Portal>
          <p>Dialog is {api().isOpen ? 'open' : 'closed'}</p>
        </>
      )}
    </Dialog.Root>
  )
}

<script setup lang="ts">
import { Teleport, ref } from 'vue'
import { Dialog } from '@ark-ui/vue'

const open = ref(false)
</script>

<template>
  <Dialog.Root v-slot="api">
    <Dialog.Trigger>Open Dialog</Dialog.Trigger>
    <Teleport to="body">
      <Dialog.Backdrop />
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog Description</Dialog.Description>
          <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Teleport>
    <p>Dialog is {{ api.isOpen ? 'open' : 'closed' }}</p>
  </Dialog.Root>
</template>

API Reference

Root

Prop	Type	Default
`aria-label`	`string`
`closeOnEscapeKeyDown`	`boolean`
`closeOnInteractOutside`	`boolean`
`defaultOpen`	`boolean`
`dir`	`'ltr' \| 'rtl'`	`"ltr"`
`finalFocusEl`	`HTMLElement \| (() => MaybeElement)`
`getRootNode`	`() => Node \| ShadowRoot \| Document`
`id`	`string`
`ids`	`Partial<{ trigger: string positioner: string backdrop: string content: string closeTrigger: string title: string description: string }>`
`initialFocusEl`	`HTMLElement \| (() => MaybeElement)`
`lazyMount`	`boolean`	`false`
`modal`	`boolean`
`onEscapeKeyDown`	`(event: KeyboardEvent) => void`
`onExitComplete`	`() => void`
`onFocusOutside`	`(event: FocusOutsideEvent) => void`
`onInteractOutside`	`(event: InteractOutsideEvent) => void`
`onOpenChange`	`(details: OpenChangeDetails) => void`
`onPointerDownOutside`	`(event: PointerDownOutsideEvent) => void`
`open`	`boolean`
`present`	`boolean`
`preventScroll`	`boolean`
`restoreFocus`	`boolean`
`role`	`'dialog' \| 'alertdialog'`	`"dialog"`
`trapFocus`	`boolean`
`unmountOnExit`	`boolean`	`false`

Title

Prop	Type	Default
`asChild`	`boolean`

Content

Prop	Type	Default
`asChild`	`boolean`

Trigger

Prop	Type	Default
`asChild`	`boolean`

Backdrop

Prop	Type	Default
`asChild`	`boolean`

Positioner

Prop	Type	Default
`asChild`	`boolean`

Description

Prop	Type	Default
`asChild`	`boolean`

CloseTrigger

Prop	Type	Default
`asChild`	`boolean`