---
title: "MazBackdrop"
description: "MazBackdrop is a flexible backdrop component that provides a foundation for modals, drawers, bottom sheets and any overlay content. It handles focus management, keyboard navigation, and animations automatically."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-backdrop"
---

# MazBackdrop

> MazBackdrop is a flexible backdrop component that provides a foundation for modals, drawers, bottom sheets and any overlay content. It handles focus management, keyboard navigation, and animations automatically.

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

> 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">` and is the foundation for [MazDialog](./maz-dialog.md), [MazDrawer](./maz-drawer.md), and [MazBottomSheet](./maz-bottom-sheet.md)

## Basic usage

MazBackdrop creates a semi-transparent overlay that covers the entire screen. Think of it like a dark blanket that appears behind your content to make it stand out.

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

const basicOpen = ref(false)
</script>

<template>
  <MazBtn @click="basicOpen = true">
    Open Backdrop
  </MazBtn>

  <MazBackdrop v-model="basicOpen" justify="center" align="center">
    <div class="my-content">
      <h3>Hello! I'm on top of the backdrop</h3>
      <p>Click outside or press Escape to close</p>
      <MazBtn @click="basicOpen = false">Close</MazBtn>
    </div>
  </MazBackdrop>
</template>

<style lang="css" scoped>
.demo-content {
  background: var(--maz-surface);
  padding: 2rem;
  border-radius: var(--maz-rounded-md);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  max-width: 400px;
  text-align: center;
}

.demo-content h3 {
  margin-top: 0;
}

.demo-content p {
  margin-bottom: 1.5rem;
  color: var(--maz-muted);
}
</style>
```

## Persistent backdrop

A persistent backdrop cannot be closed by clicking outside or pressing Escape. Perfect for important confirmations!

```html
<MazBackdrop v-model="persistentOpen" persistent align="center" justify="center">
  <div class="my-content">
    <h3>I'm persistent!</h3>
    <p>You can only close me by clicking the button below</p>
    <MazBtn @click="persistentOpen = false" color="destructive">
      Force Close
    </MazBtn>
  </div>
</MazBackdrop>
```

## Content positioning

You can control where your content appears using `justify` and `align` props. It's like choosing where to place a sticker on your screen!

```html
<!-- Top Left -->
<MazBackdrop v-model="topLeftOpen" justify="start" align="start" content-padding>
  <div class="my-content">
    <h3>I'm at the top left!</h3>
    <MazBtn @click="topLeftOpen = false">Close</MazBtn>
  </div>
</MazBackdrop>

<!-- Center -->
<MazBackdrop v-model="centerOpen" justify="center" align="center" content-padding>
  <div class="my-content">
    <h3>I'm perfectly centered!</h3>
    <MazBtn @click="centerOpen = false">Close</MazBtn>
  </div>
</MazBackdrop>

<!-- Bottom Right -->
<MazBackdrop v-model="bottomRightOpen" justify="end" align="end" content-padding>
  <div class="my-content">
    <h3>I'm at the bottom right!</h3>
    <MazBtn @click="bottomRightOpen = false">Close</MazBtn>
  </div>
</MazBackdrop>
```

## Custom animations

MazBackdrop comes with built-in animations, but you can customize them with the `transition-name` prop.

```html
<MazBackdrop v-model="animatedOpen" transition-name="modal-anim">
  <div class="my-content">
    <h3>I slide and scale in!</h3>
    <p>This uses the same animation as MazDialog</p>
    <MazBtn @click="animatedOpen = false">Close</MazBtn>
  </div>
</MazBackdrop>
```

## Accessibility features

MazBackdrop automatically handles:
- **Focus trap**: Tab navigation stays within your content
- **Keyboard support**: Escape key to close (unless persistent)
- **Screen readers**: Proper ARIA attributes for accessibility
- **Scroll lock**: Prevents background scrolling when open

These features work automatically - you don't need to do anything extra!

## MazBackdrop API

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

### Props

- `model-value` (`boolean`, default: `false`, `v-model`): Modal's model value.
- `teleport-selector` (`string`, default: `"body"`): Teleport selector.
- `before-close` (`(() => void | Promise<void>)`): Function called before modal is close.
- `persistent` (`boolean`, default: `false`): Persistent dialog (not closable by clicking outside and remove close button).
- `close-on-escape` (`boolean`, default: `true`): Prevent close on escape key.
- `transition-name` (`string`, default: `"backdrop-anim"`): Transition name.
- `backdrop-class` (`ClassValue`): Backdrop class.
- `backdrop-content-class` (`ClassValue`): Backdrop content class.
- `content-padding` (`boolean`, default: `false`): Add padding to the content.
- `justify` (`"none" | "center" | "end" | "start" | "space-between" | "space-around"`, default: `"none"`): Justify content.
- `align` (`"none" | "center" | "end" | "start"`, default: `"none"`): 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
- `@before-close` (payload: `value?: void | undefined`): Emitted before modal is close

### Slots

- `#default`: Place your content here Bindings: `close: () => void` (close function).

### Exposed (template ref)

- `onBackdropAnimationLeave`: Animation leave event
- `close`: Close the backdrop
- `present`: The present state of the backdrop
- `toggleModal`: Toggle the backdrop
- `onKeyPress`: Key press event