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.

Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started

TIP

This component uses <Teleport to="body"> and is the foundation for MazDialog, MazDrawer, and MazBottomSheet

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.

<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!

<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!

<!-- 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.

<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!

Props

Name	Description	Type	Required	Default	Possible values
model-value	v-model Modal's model value	boolean	No	false	-
teleport-selector	Teleport selector	string	No	"body"	-
before-close	Function called before modal is close	(() => void | Promise<void>)	No	-	-
persistent	Persistent dialog (not closable by clicking outside and remove close button)	boolean	No	false	-
close-on-escape	Prevent close on escape key	boolean	No	true	-
transition-name	Transition name	string	No	"backdrop-anim"	-
backdrop-class	Backdrop class	ClassValue	No	-	-
backdrop-content-class	Backdrop content class	ClassValue	No	-	-
content-padding	Add padding to the content	boolean	No	false	-
justify	Justify content	"none" | "center" | "end" | "start" | "space-between" | "space-around"	No	"none"	'none' | 'center' | 'end' | 'start' | 'space-between' | 'space-around'
align	Align content	"none" | "center" | "end" | "start"	No	"none"	'none' | 'center' | 'end' | 'start'
variant	Variant	"bottom-sheet" | "dialog" | "drawer"	No	-	'bottom-sheet' | 'dialog' | 'drawer'
aria-labelledby	ID for aria-labelledby	string	No	-	-
aria-describedby	ID for aria-describedby	string	No	-	-

Events

Event name	Payload	Description
update:model-value	value: boolean	Emitted when modal is open or close
open	value?: void | undefined	Emitted when modal is open
close	value?: void | undefined	Emitted when modal is close
before-close	value?: void | undefined	Emitted before modal is close

Slots

Name	Description	Bindings
default	Place your content here	close () => void - close function

Expose

onBackdropAnimationLeave

Animation leave event

close

Close the backdrop

present

The present state of the backdrop

toggleModal

Toggle the backdrop

onKeyPress

Key press event