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: hsl(var(--maz-background));
  padding: 2rem;
  border-radius: var(--maz-radius);
  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: hsl(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
model-value	v-model	boolean	No
teleport-selector	Teleport selector	string	No
before-close	Function called before modal is close	TSFunctionType	No
persistent	Persistent dialog (not closable by clicking outside and remove close button)	boolean	No
close-on-escape	Prevent close on escape key	boolean	No
transition-name	Transition name	string	No
backdrop-class	Backdrop class	Native type	No
backdrop-content-class	Backdrop content class	Native type	No
content-padding	Add padding to the content	boolean	No
justify	Justify content	"center" | "end" | "start" | "space-between" | "space-around" | "none"	No
align	Align content	"center" | "end" | "start" | "none"	No
variant	Variant	"bottom-sheet" | "dialog" | "drawer"	No
aria-labelledby	ID for aria-labelledby	string	No
aria-describedby	ID for aria-describedby	string	No

Events

Event name	Properties	Description
open		Emitted when modal is open
close		Emitted when modal is close
update:model-value	value boolean - The value of the model	Emitted when modal is open or close
before-close		Emitted before modal is close

Slots

Name	Description	Bindings
default	Place your content here	close Function - close function

Expose

onBackdropAnimationLeave

Animation leave event
@description This is used to handle animation leave events

close

Close the backdrop
@description This is used to close the backdrop

present

The present state of the backdrop
@description This is used to check if the backdrop is present (open)

toggleModal

Toggle the backdrop
@description This is used to toggle the backdrop
@param The value to toggle the backdrop (optional)

onKeyPress

Key press event
@description This is used to handle key press events