Dialog
A modal dialog that appears over the page and traps focus.
A modal panel that overlays the page. Focus is trapped inside while open and restored to the trigger when closed. Screen readers are informed via role="dialog" and aria-modal.
For confirmations requiring a required response, use Alert Dialog instead.
Anatomy
#trigger: Element that opens the dialog.#overlay: Optional backdrop content behind the dialog.#header: Region containing the title and close control.#title: Dialog accessible title.#description: Supplementary description text.#body: Main content area.#footer: Action buttons.
Usage
Examples
Custom header with close button
Use #header when the close control belongs beside the title.
<template>
<Tabs
:items="tabs"
v-model="active"
>
<template #tab="{ item, isActive }">
<span :class="['tab', { 'tab--active': isActive }]">
{{ item.label }}
</span>
</template>
<template #panel-account>Account content.</template>
<template #panel-security>Security content.</template>
</Tabs>
</template>
Fullscreen dialog
Use fullscreen for flows that should take over the viewport.
<Button class="rounded-md bg-black px-3 py-2 text-white">
Save
</Button>
Prevent close on backdrop click
Disable backdrop dismissal when the user must make an explicit choice.
<script setup lang="ts">
import { ref } from 'vue'
import { Dialog } from 'akaza-ui'
const dialog = ref()
function showConfirmation() {
dialog.value?.open()
}
</script>
<template>
<Dialog ref="dialog">
<template #body>Are you sure?</template>
<template #footer="{ close }">
<button @click="close">Dismiss</button>
</template>
</Dialog>
<button @click="showConfirmation">Show confirmation</button>
</template>
Programmatic control
Use the exposed API when opening is driven outside the trigger slot.
<script setup lang="ts">
import { ref } from 'vue'
import { Tabs } from 'akaza-ui'
const active = ref('account')
const items = [
{ value: 'account', label: 'Account' },
{ value: 'security', label: 'Security' },
]
</script>
<template>
<Tabs v-model="active" :items="items" aria-label="Settings">
<template #panel-account>Account settings…</template>
<template #panel-security>Security settings…</template>
</Tabs>
</template>
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Convenience title. Slot #title takes priority. |
description | string | — | Convenience description. Slot #description takes priority. |
ariaLabel | string | — | Fallback accessible name when no title is rendered. |
closeOnBackdropClick | boolean | true | Close when clicking the overlay. |
fullscreen | boolean | false | Expand the dialog to fill the viewport. |
teleport | string | false | "body" | Teleport target. |
transition | string | false | "akaza-dialog" | Named Vue transition. |
duration | number | 100 | Transition duration in ms. |
as | string | "div" | Root element tag. |
ui | DialogUi | — | CSS class overrides. |
Slots
| Slot | Scoped props | Description |
|---|---|---|
trigger | { isOpen, open, close, toggle } | Element that opens the dialog. |
overlay | — | Backdrop element. |
header | { close, titleId } | Header region. |
title | — | Dialog title. Defaults to the title prop. |
description | — | Description text. Defaults to the description prop. |
body | { close, descriptionId } | Main content area. |
footer | { close } | Action buttons region. |
Exposed methods
| Method | Signature | Description |
|---|---|---|
open | (reason?, event?) => void | Opens the dialog. |
close | (reason?, event?) => void | Closes the dialog. |
toggle | (reason?, event?) => void | Toggles the dialog. |
titleId | string | Auto-generated id for the title element. |
descriptionId | string | Auto-generated id for the description element. |
Emits
| Event | Payload | Description |
|---|---|---|
open-change | [open: boolean, details] | Fired when the open state changes. |
UI Options
| Key | Description |
|---|---|
overlay | The backdrop overlay. |
content | The dialog panel. |
header | The header region. |
title | The title element. |
description | The description element. |
body | The body region. |
footer | The footer region. |
Styling Hooks
| UI key | CSS class | Data attrs |
|---|---|---|
overlay | akaza-dialog-overlay | data-akaza-state |
content | akaza-dialog-content | data-akaza-state, data-akaza-fullscreen |
header | akaza-dialog-header | — |
title | akaza-dialog-title | — |
description | akaza-dialog-description | — |
body | akaza-dialog-body | — |
footer | akaza-dialog-footer | — |
Dialog renders trigger slot content plus teleported overlay/content. Use ui keys instead of relying on plain class fallthrough.
Keyboard
| Key | Behavior |
|---|---|
Tab / Shift + Tab | Cycles through focusable controls inside open dialog. |
Escape | Closes topmost dialog and restores prior focus. |
Opening moves focus inside, locks page scroll, and makes background content inert while modal is active.