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.

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="danger">
      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