---
title: "MazDialog"
description: "MazDialog is a standalone dialog component to show important informations to the user or propose specific action. Many options are available. You can hide the header or the footer, full-size layout, differents states etc."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-dialog"
---

# MazDialog

> MazDialog is a standalone dialog component to show important informations to the user or propose specific action. Many options are available. You can hide the header or the footer, full-size layout, differents states etc.

- Package: `maz-ui`
- Import: `import MazDialog from 'maz-ui/components/MazDialog'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-dialog

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

**Tip:**

This component uses `<Teleport to="body">` with [MazBackdrop](./maz-backdrop.md), so you can implement this component anywhere and it inherits all its props

## Basic usage

```vue
<script setup>
import MazDialog from 'maz-ui/components/MazDialog'
import { ref } from 'vue'

const isOpen = ref(false)
</script>

<template>
  <MazBtn @click="isOpen = true">
    Open Dialog
  </MazBtn>

  <MazDialog v-model="isOpen" title="Dialog Title">
    <p>
      Your content
    </p>

    <template #footer="{ close }">
      <MazBtn @click="close">
        Confirm
      </MazBtn>
    </template>
  </MazDialog>
</template>
```

## Scrollable

For long content, you can enable scrolling in content part (Header and footer slot remain visible at top and bottom)

```html
<MazDialog v-model="scollableOpened" title="Dialog Title" max-height="400px" scrollable>
  <template #title> Scrollable Dialog Title </template>

  <template #default>
    <p v-for="i in 40" :key="i" style="padding-bottom: 2rem">Scroll down</p>
  </template>

  <template #footer>
    <MazBtn @click="scollableOpened = false"> Confirm </MazBtn>
  </template>
</MazDialog>
```

## Width

On tablet and up, the dialog is sized by two CSS variables coming from the active theme preset (`components.dialog`):

- `--maz-dialog-max-width` (default `38rem`)
- `--maz-dialog-min-width` (default `32rem`)

You can set these defaults globally per preset - see [the theme `components.dialog` documentation](../ecosystem/themes.md#dialog-sizing). To change the width of a single dialog, pass the `max-width` / `min-width` props - they always override the preset:

```vue
<template>
  <MazDialog
    v-model="isOpen"
    title="Custom width"
    max-width="50rem"
    min-width="40rem"
  >
    <p>This dialog overrides the preset width through props.</p>
  </MazDialog>
</template>
```

**Tip:**

The default widths are expressed in `rem`, so they scale with the preset's `base-font-size`. Presets with a larger base size (e.g. `ocean` at `16px`) ship rem values adjusted to keep the rendered pixel width consistent across presets.

## Accessibility

- The dialog is a modal `dialog` (`aria-modal`), labelled by its title and described by its content (override them with the `aria-labelledby` / `aria-describedby` props).
- The focus moves into the dialog on open, stays trapped inside and goes back to the previous element on close. Esc closes it (`close-on-escape`).
- While it is open, the rest of the page is `inert` (no focus, no click, hidden from assistive technologies), except the toasts and the live regions.

## MazDialog API

`import MazDialog from 'maz-ui/components/MazDialog'`

### Props

- `model-value` (`boolean`, `v-model`): Modal's model value.
- `title` (`string`): Title of the modal in header.
- `hide-close-button` (`boolean`): Remove the close button in header.
- `max-width` (`string`, default: `"var(--maz-dialog-max-width, 38rem)"`): Modal's max-width.
- `min-width` (`string`, default: `"var(--maz-dialog-min-width, 32rem)"`): Modal's min-width.
- `scrollable` (`boolean`): Modal's content becomes scrollable - warning: a overflow is applied.
- `persistent` (`boolean`): Persistent dialog (not closable by clicking outside and remove close button).
- `teleport-selector` (`string`): Teleport selector.
- `before-close` (`(() => void | Promise<void>)`): Function called before modal is close.
- `close-on-escape` (`boolean`, default: `true`): Prevent close on escape key.
- `transition-name` (`string`): Transition name.
- `backdrop-class` (`ClassValue`): Backdrop class.
- `backdrop-content-class` (`ClassValue`): Backdrop content class.
- `content-padding` (`boolean`): Add padding to the content.
- `justify` (`"none" | "center" | "end" | "start" | "space-between" | "space-around"`): Justify content.
- `align` (`"none" | "center" | "end" | "start"`): Align content.
- `variant` (`"bottom-sheet" | "dialog" | "drawer"`): Variant.
- `aria-labelledby` (`string`): ID for aria-labelledby.
- `aria-describedby` (`string`): ID for aria-describedby.

### Events

- `@update:model-value` (payload: `value: boolean`): emitted when modal is open or close
- `@open` (payload: `value?: void | undefined`): emitted when modal is open
- `@close` (payload: `value?: void | undefined`): emitted when modal is close

### Slots

- `#header`: Header slot Bindings: `close: () => void` (close function).
- `#title`: Title slot in the header
- `#default`: Default content Bindings: `close: () => void` (close function).
- `#footer`: Footer slot Bindings: `close: () => void` (close function).

### Exposed (template ref)

- `close`: Close the dialog