Dialog

ARIAGitHubnpm
A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
<script setup lang="ts">
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'akar';
import './styles.css';
</script>

<template>
  <div class="akar-demo akar-demo-Dialog">
    <DialogRoot>
      <DialogTrigger
        class="Button grass"
      >
        Edit profile
      </DialogTrigger>
      <DialogPortal>
        <DialogOverlay class="DialogOverlay" />
        <DialogContent
          class="DialogContent"
        >
          <DialogTitle class="DialogTitle">
            Edit profile
          </DialogTitle>
          <DialogDescription class="DialogDescription">
            Make changes to your profile here. Click save when you're done.
          </DialogDescription>
          <fieldset class="Fieldset">
            <label
              class="Label"
              for="name"
            > Name </label>
            <input
              id="name"
              class="Input"
              defaultValue="Pedro Duarte"
            >
          </fieldset>
          <fieldset class="Fieldset">
            <label
              class="Label"
              for="username"
            > Username </label>
            <input
              id="username"
              class="Input"
              defaultValue="@peduarte"
            >
          </fieldset>
          <div :style="{ display: 'flex', marginTop: 25, justifyContent: 'flex-end' }">
            <DialogClose as-child>
              <button
                class="Button green"
              >
                Save changes
              </button>
            </DialogClose>
          </div>
          <DialogClose
            class="IconButton"
            aria-label="Close"
          >
            <PIcon name="i-lucide-x" />
          </DialogClose>
        </DialogContent>
      </DialogPortal>
    </DialogRoot>
  </div>
</template>

Features

  • Supports modal and non-modal modes.
  • Focus is automatically trapped when modal.
  • Can be controlled or uncontrolled.
  • Manages screen reader announcements with Title andDescription components.
  • Esc closes the component automatically.

Installation

Install the component from your command line.

pnpm add akar

Anatomy

Import all parts and piece them together.

<script setup>
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'akar';
</script>

<template>
  <DialogRoot>
    <DialogTrigger />
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle />
        <DialogDescription />
        <DialogClose />
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

API Reference

Root

Contains all the parts of a dialog

PropDefaultType
defaultOpen
false
boolean

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

modal
true
boolean

The modality of the dialog When set to true,

interaction with outside elements will be disabled and only dialog content will be visible to screen readers.

open
boolean

The controlled open state of the dialog. Can be binded as v-model:open.

unmountOnHide
true
boolean

When set to false, the dialog content will not be unmounted when closed, but instead hidden with CSS.

Useful for SEO or when you want to improve performance by not remounting the component on every open.

EventPayload
update:open
value: boolean

Event handler called when the open state of the dialog changes.

Slot (default)Payload
open
boolean

Current open state

close
(): void

Close the dialog

DialogRoot.vue source

Trigger

The button that opens the dialog

PropDefaultType
as
"button"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

DialogTrigger.vue source

Data attribute Value
[data-state]
"open" | "closed"

Portal

When used, portals your overlay and content parts into the body.

PropDefaultType
defer
boolean

Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+)

reference

disabled
boolean

Disable teleport and render the component inline

reference

forceMount
boolean

Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.

to
string | HTMLElement

Vue native teleport component prop :to

reference

DialogPortal.vue source

Overlay

A layer that covers the inert portion of the view when the dialog is open.

Defer mounting with forceMount / Presence. See the animation guide.
PropDefaultType
as
"div"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

forceMount
boolean

Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.

DialogOverlay.vue source

Data attribute Value
[data-state]
"open" | "closed"

Content

Contains content to be rendered in the open dialog

Defer mounting with forceMount / Presence. See the animation guide.
PropDefaultType
as
"div"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

disableOutsidePointerEvents
boolean

When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element.

forceMount
boolean

Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.

EventPayload
closeAutoFocus
event: Event

Event handler called when auto-focusing on close. Can be prevented.

escapeKeyDown
event: KeyboardEvent

Event handler called when the escape key is down. Can be prevented.

focusOutside
event: FocusOutsideEvent

Event handler called when the focus moves outside of the DismissableLayer. Can be prevented.

interactOutside
event: PointerDownOutsideEvent | FocusOutsideEvent

Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented.

openAutoFocus
event: Event

Event handler called when auto-focusing on open. Can be prevented.

pointerDownOutside
event: PointerDownOutsideEvent

Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented.

DialogContent.vue source

Data attribute Value
[data-state]
"open" | "closed"

Close

The button that closes the dialog

PropDefaultType
as
"button"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

DialogClose.vue source

Title

An accessible title to be announced when the dialog is opened.

If you want to hide the title, wrap it inside our Visually Hidden utility like this <VisuallyHidden asChild>.

PropDefaultType
as
"h2"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

DialogTitle.vue source

Description

An optional accessible description to be announced when the dialog is opened.

If you want to hide the description, wrap it inside our Visually Hidden utility like this <VisuallyHidden asChild>. If you want to remove the description entirely, remove this part and pass :aria-describedby="undefined" to DialogContent.

PropDefaultType
as
"p"
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

DialogDescription.vue source

Examples

Nested dialog

You can nest multiple layers of dialogs.

<script setup lang="ts">
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'akar';
</script>

<template>
  <div class="akar-demo akar-demo-DialogNested">
    <div>
      <DialogRoot>
        <DialogTrigger
          class="color-grass11 shadow-blackA7 hover:bg-mauve3 leading-none font-semibold px-[15px] rounded-[4px] bg-white inline-flex h-[35px] shadow-[0_2px_10px] items-center justify-center focus:outline-none focus:shadow-[0_0_0_2px] focus:shadow-black"
        >
          Open Dialog
        </DialogTrigger>
        <DialogPortal>
          <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow inset-0 fixed z-30" />
          <DialogContent
            class="data-[state=open]:animate-contentShow p-[25px] rounded-[6px] bg-white max-h-[85vh] max-w-[450px] w-[90vw] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] translate-x-[-50%] translate-y-[-50%] left-[50%] top-[50%] fixed z-[100] focus:outline-none"
          >
            <DialogTitle class="color-mauve12 text-[17px] font-semibold m-0">
              First Dialog
            </DialogTitle>
            <DialogDescription class="color-mauve11 text-sm leading-normal mb-5 mt-[10px]">
              First dialog.
            </DialogDescription>

            <div class="mt-[25px] flex gap-4 justify-end">
              <DialogClose as-child>
                <button
                  class="bg-green4 color-green11 hover:bg-green5 focus:shadow-green7 leading-none font-semibold px-[15px] rounded-[4px] inline-flex h-[35px] items-center justify-center focus:outline-none focus:shadow-[0_0_0_2px]"
                >
                  Close
                </button>
              </DialogClose>

              <DialogRoot>
                <DialogTrigger
                  class="bg-green9 shadow-blackA7 hover:bg-green10 color-white leading-none font-semibold px-[15px] rounded-[4px] inline-flex h-[35px] shadow-[0_2px_10px] items-center justify-center focus:outline-none focus:shadow-[0_0_0_2px] focus:shadow-black"
                >
                  Open second
                </DialogTrigger>

                <DialogPortal>
                  <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow inset-0 fixed z-30" />
                  <DialogContent
                    class="data-[state=open]:animate-contentShow p-[25px] rounded-[6px] bg-white max-h-[85vh] max-w-[450px] w-[90vw] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] translate-x-[-50%] translate-y-[-50%] left-[50%] top-[50%] fixed z-[100] focus:outline-none"
                  >
                    <DialogTitle class="color-mauve12 text-[17px] font-semibold m-0">
                      Second Dialog
                    </DialogTitle>
                    <DialogDescription class="color-mauve11 text-sm leading-normal mb-5 mt-[10px]">
                      Second dialog.
                    </DialogDescription>

                    <div class="flex justify-end">
                      <DialogClose as-child>
                        <button
                          class="bg-green4 color-green11 hover:bg-green5 focus:shadow-green7 leading-none font-semibold px-[15px] rounded-[4px] inline-flex h-[35px] items-center justify-center focus:outline-none focus:shadow-[0_0_0_2px]"
                        >
                          Close
                        </button>
                      </DialogClose>
                    </div>
                  </DialogContent>
                </DialogPortal>
              </DialogRoot>
            </div>
            <DialogClose
              class="color-grass11 hover:bg-green4 focus:shadow-green7 appearance-none rounded-full inline-flex h-[25px] w-[25px] items-center right-[10px] top-[10px] justify-center absolute focus:outline-none focus:shadow-[0_0_0_2px]"
              aria-label="Close"
            >
              <PIcon name="i-lucide-x" />
            </DialogClose>
          </DialogContent>
        </DialogPortal>
      </DialogRoot>
    </div>
  </div>
</template>

Close after asynchronous form submission

Use the controlled props to programmatically close the Dialog after an async operation has completed.

<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'akar'

const wait = () => new Promise(resolve => setTimeout(resolve, 1000))
const open = ref(false)
</script>

<template>
  <DialogRoot v-model:open="open">
    <DialogTrigger>Open</DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <form
          @submit.prevent="
            (event) => {
              wait().then(() => (open = false));
            }
          "
        >
          <!-- some inputs -->
          <button type="submit">
            Submit
          </button>
        </form>
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

Scrollable overlay

Move the content inside the overlay to render a dialog with overflow.

// index.vue
<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'akar';
import './styles.css';
</script>

<template>
  <DialogRoot>
    <DialogTrigger />
    <DialogPortal>
      <DialogOverlay class="DialogOverlay">
        <DialogContent class="DialogContent">
          ...
        </DialogContent>
      </DialogOverlay>
    </DialogPortal>
  </DialogRoot>
</template>
/* styles.css */
.DialogOverlay {
  background: rgba(0 0 0 / 0.5);
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  display: grid;
  place-items: center;
  overflow-y: auto;
}

.DialogContent {
  min-width: 300px;
  background: white;
  padding: 30px;
  border-radius: 4px;
}

However, there's a caveat to this approach, where user might click on the scrollbar and close the dialog unintentionally. There's no universal solution that would fix this issue for now, however you can add the following snippet to DialogContent to prevent closing of modal when clicking on scrollbar.

<DialogContent
  @pointer-down-outside="(event) => {
    const originalEvent = event.detail.originalEvent;
    const target = originalEvent.target as HTMLElement;
    if (originalEvent.offsetX > target.clientWidth || originalEvent.offsetY > target.clientHeight) {
      event.preventDefault();
    }
  }"
>

Custom portal container

Customise the element that your dialog portals into.

<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'akar'

const container = ref(null)
</script>

<template>
  <div>
    <DialogRoot>
      <DialogTrigger />
      <DialogPortal to="container">
        <DialogOverlay />
        <DialogContent>...</DialogContent>
      </DialogPortal>
    </DialogRoot>

    <div ref="container" />
  </div>
</template>

Disable close on interaction outside

If a global toast (or similar overlay) should not dismiss the dialog when clicked, cancel interact-outside when the event target is inside that overlay.

<DialogContent
  @interact-outside="(event) => {
    const target = event.target as HTMLElement
    if (target?.closest('[data-sonner-toaster]')) event.preventDefault()
  }"
>
  …
</DialogContent>

Accessibility

Adheres to the Dialog WAI-ARIA design pattern.

Close icon button

When providing an icon (or font icon), remember to label it correctly for screen reader users.

<template>
  <DialogRoot>
    <DialogTrigger />
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle />
        <DialogDescription />
        <DialogClose aria-label="Close">
          <span aria-hidden="true">×
        </DialogClose>
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

Close using slot props

Alternatively, you can use the close method provided by the DialogRoot slot props to programmatically close the dialog.

<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'akar'
</script>

<template>
  <DialogRoot v-slot="{ close }">
    <DialogTrigger>Open</DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <form>
          <!-- some inputs -->
          <button type="submit" @click="close">
            Submit
          </button>
        </form>
      </DialogContent>
      <DialogFooter>
        <button type="submit" @click="close">
          Submit
        </button>
      </DialogFooter>
    </DialogPortal>
  </DialogRoot>
</template>

Keyboard Interactions

Key Description
Space
Opens/closes the dialog
Enter
Opens/closes the dialog
Tab
Moves focus to the next focusable element.
Shift + Tab
Moves focus to the previous focusable element.
Esc
Closes the dialog and moves focus to DialogTrigger.

Custom APIs

Create your own API by abstracting the primitive parts into your own component.

Abstract the overlay and the close button

This example abstracts the DialogOverlay and DialogClose parts.

Usage

<script setup>
import { Dialog, DialogContent, DialogTrigger } from './your-dialog';
</script>

<template>
  <Dialog>
    <DialogTrigger>Dialog trigger</DialogTrigger>
    <DialogContent>Dialog Content</DialogContent>
  </Dialog>
</template>

Implementation

export { DialogRoot as Dialog, DialogTrigger } from 'akar';
// your-dialog.ts
export { default as DialogContent } from 'DialogContent.vue';
<!-- DialogContent.vue -->
<script setup lang="ts">
import type { DialogContentEmits, DialogContentProps } from 'akar';
import { Cross2Icon } from '@radix-icons/vue';
import { DialogClose, DialogContent, DialogOverlay, DialogPortal, useForwardPropsEmits } from 'akar';

const props = defineProps<DialogContentProps>();
const emits = defineEmits<DialogContentEmits>();

const forwarded = useForwardPropsEmits(props, emits);
</script>

<template>
  <DialogPortal>
    <DialogOverlay />
    <DialogContent v-bind="forwarded">
      <slot />

      <DialogClose>
        <Cross2Icon />
        <span class="sr-only">Close
        </span>
      </DialogClose>
    </DialogContent>
  </DialogPortal>
</template>