Dialog
A modal window that appears on top of the main content.
Dialog Title
Dialog Description
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-partattribute 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'
export 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 { Portal } from 'solid-js/web'
import { Dialog } from '@ark-ui/solid'
export const Basic = () => {
return (
<Dialog.Root open>
<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 } from 'vue'
import { Dialog } from '@ark-ui/vue'
</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 { useState } from 'react'
import { Dialog, Portal } from '@ark-ui/react'
export const Controlled = () => {
const [isOpen, setIsOpen] = useState(false)
return (
<>
<button type="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 { createSignal } from 'solid-js'
import { Portal } from 'solid-js/web'
import { Dialog } from '@ark-ui/solid'
export const Controlled = () => {
const [isOpen, setIsOpen] = createSignal(false)
return (
<>
<button type="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="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.
Story not foundStory not foundStory not foundUsing 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:
Story not foundStory not foundStory not foundAPI Reference
Root
| Prop | Type | Default |
|---|---|---|
aria-labelHuman readable label for the dialog, in event the dialog title is not rendered | string | |
closeOnEscapeWhether to close the dialog when the escape key is pressed | boolean | |
closeOnInteractOutsideWhether to close the dialog when the outside is clicked | boolean | |
defaultOpenThe initial open state of the dialog when it is first rendered.
Use when you do not need to control its open state. | boolean | |
dirThe document's text/writing direction. | 'rtl' | 'ltr' | "ltr" |
finalFocusElElement to receive focus when the dialog is closed | HTMLElement | (() => MaybeElement) | |
getRootNodeA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron. | () => ShadowRoot | Node | Document | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the dialog. Useful for composition. | Partial<{
trigger: string
positioner: string
backdrop: string
content: string
closeTrigger: string
title: string
description: string
}> | |
initialFocusElElement to receive focus when the dialog is opened | HTMLElement | (() => MaybeElement) | |
lazyMountWhether to enable lazy mounting | boolean | false |
modalWhether to prevent pointer interaction outside the element and hide all content below it | boolean | |
onEscapeKeyDownCallback to be invoked when the escape key is pressed | (event: KeyboardEvent) => void | |
onExitCompleteFunction called when the animation ends in the closed state. | () => void | |
onFocusOutsideFunction called when the focus is moved outside the component | (event: FocusOutsideEvent) => void | |
onInteractOutsideFunction called when an interaction happens outside the component | (event: InteractOutsideEvent) => void | |
onOpenChangeCallback to be invoked when the dialog is opened or closed | (details: OpenChangeDetails) => void | |
onPointerDownOutsideFunction called when the pointer is pressed down outside the component | (event: PointerDownOutsideEvent) => void | |
openWhether the dialog is open | boolean | |
presentWhether the node is present (controlled by the user) | boolean | |
preventScrollWhether to prevent scrolling behind the dialog when it's opened | boolean | |
restoreFocusWhether to restore focus to the element that had focus before the dialog was opened | boolean | |
roleThe dialog's role | 'dialog' | 'alertdialog' | "dialog" |
trapFocusWhether to trap focus inside the dialog when it's opened | boolean | |
unmountOnExitWhether to unmount on exit. | boolean | false |
Backdrop
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
CloseTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Content
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Description
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Positioner
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Title
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Trigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Previous
Date PickerNext
Editable