MazBottomSheet

MazBottomSheet is a standalone component like a simple dialog but anchored at the bottom of the screen. Full-width on mobile and constrained/centered on desktop, with a header (icon, title, close button), a footer and many replaceable slots. Useful for mobile UX.

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

TIP

This component uses the <Teleport to="body"> with MazBackdrop, so you can implement this component anywhere and it inherits all its props (persistent, closeOnEscape, etc.)

Basic usage

The sheet has a header (with the title and a close button) and an optional footer slot. It opens full-width on mobile and is constrained/centered on desktop (see Max width).

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

const basicOpened = ref(false)
</script>

<template>
  <MazBtn @click="basicOpened = true">
    Open Bottom Sheet
  </MazBtn>

  <MazBottomSheet v-model="basicOpened" title="Bottom Sheet Title">
    <p>Your content goes here.</p>

    <template #footer="{ close }">
      <MazBtn color="transparent" @click="close">
        Cancel
      </MazBtn>
      <MazBtn @click="close">
        Confirm
      </MazBtn>
    </template>
  </MazBottomSheet>
</template>

Swipe to close (iOS-like)

By default a drag handle (grab bar) is shown at the top of the sheet, and you can close the sheet by dragging that handle down - the sheet follows your pointer and either dismisses (past the threshold) or snaps back. This works with both touch and mouse.

Disable it with :swipe-to-close="false" (the handle is then hidden too), or replace the handle with the #handle slot. A persistent sheet never dismisses on swipe: it snaps back instead.

<!-- enabled by default -->
<MazBottomSheet v-model="swipeOpened" title="Drag me down">
  <p>Grab the bar at the top and drag down to close.</p>
</MazBottomSheet>

<!-- disable the handle and the gesture -->
<MazBottomSheet v-model="swipeOpened" :swipe-to-close="false" title="No swipe" />

<!-- custom handle -->
<MazBottomSheet v-model="swipeOpened" title="Custom handle">
  <template #handle>
    <span class="h-1.5 w-12 rounded-full bg-primary" />
  </template>
</MazBottomSheet>

Header with an icon

Pass an icon (an icon value or a full MazIconProps object) to display it on the left of the title.

<MazBottomSheet v-model="iconOpened" title="Notifications" icon="/bell.svg">
  <p>You have 3 new notifications.</p>

  <template #footer="{ close }">
    <MazBtn @click="close">Mark all as read</MazBtn>
  </template>
</MazBottomSheet>

Replaceable slots

Everything in the header is replaceable: use #icon and #title to customize parts of the default header, or #header to replace the whole header (you get the close function as a binding).

<MazBottomSheet v-model="slotsOpened">
  <template #icon>
    <MazAvatar src="/avatar.jpg" size="sm" />
  </template>

  <template #title>
    <span class="text-primary">Custom title</span>
  </template>

  <p>The icon and the title slots are fully replaceable.</p>
</MazBottomSheet>

<!-- or replace the whole header -->
<MazBottomSheet v-model="slotsOpened">
  <template #header="{ close }">
    <div class="flex items-center justify-between p-4">
      <strong>My header</strong>
      <MazBtn size="sm" color="transparent" @click="close">Close</MazBtn>
    </div>
  </template>
</MazBottomSheet>

Max width

On mobile the sheet is always full-width. From the tablet breakpoint and up, it is constrained to max-width and centered horizontally. The default max-width is 35rem; pass the max-width prop (a MazSizeUnit) to override it.

<MazBottomSheet v-model="wideOpened" title="Wide sheet" max-width="60rem">
  <p>This sheet is constrained to 60rem on desktop and full-width on mobile.</p>
</MazBottomSheet>

Without header

Hide the whole header with hide-header, or only the close button with hide-close-button.

<MazBottomSheet v-model="noHeaderOpened" hide-header>
  <div class="flex flex-col gap-3 text-center">
    <p>No header here, you control the whole layout.</p>
    <MazBtn @click="noHeaderOpened = false">Got it</MazBtn>
  </div>
</MazBottomSheet>

Persistent

A persistent sheet cannot be closed by clicking outside or pressing escape, and the close button is removed. Provide your own action to close it.

<MazBottomSheet v-model="persistentOpened" title="Action required" persistent>
  <p>You must confirm before closing this sheet.</p>

  <template #footer>
    <MazBtn @click="persistentOpened = false">I understand</MazBtn>
  </template>
</MazBottomSheet>

Full example

Nike Air Max

Premium Running Shoes

Price:$129.99

<script setup>
import MazBottomSheet from 'maz-ui/components/MazBottomSheet'
import { reactive, ref } from 'vue'

const isProductOpen = ref(false)
const quantity = ref(1)
const selectedOptions = reactive({ size: '', color: '' })

function openProductOptions() {
  isProductOpen.value = true
}
</script>

<template>
  <MazBtn color="primary" @click="openProductOptions">
    Customize Options
  </MazBtn>

  <MazBottomSheet v-model="isProductOpen" title="Customize Your Shoes" icon="/cog.svg" :padding="false">
    <div class="space-y-6 p-6">
      <h4 class="mb-3 text-lg font-semibold">
        Select Size
      </h4>
      <div class="grid grid-cols-4 gap-2">
        <MazBtn
          v-for="size in sizes"
          :key="size"
          :color="selectedOptions.size === size ? 'primary' : 'secondary'"
          size="sm"
          @click="selectedOptions.size = size"
        >
          {{ size }}
        </MazBtn>
      </div>
    </div>

    <template #footer="{ close }">
      <MazBtn color="transparent" @click="close">
        Cancel
      </MazBtn>
      <MazBtn color="primary" @click="addToCart">
        Add to Cart (${{ (129.99 * quantity).toFixed(2) }})
      </MazBtn>
    </template>
  </MazBottomSheet>
</template>

Accessibility

The bottom sheet is a modal dialog labelled by its title and described by its content. The focus is trapped inside while it is open, Esc closes it, and the rest of the page is inert (except the toasts and the live regions).

Props

Name	Description	Type	Required	Default	Possible values
model-value	v-model Modal's model value	boolean	No	-	-
title	Title of the bottom sheet in the header	string	No	-	-
icon	Icon displayed on the left of the header. Accepts an icon value or a full MazIconProps object.	MazIconLike	No	-	-
max-width	Bottom sheet's max-width, applied from the tablet breakpoint and up (full-width below).	``${number}rem|${number}px|${number}em|${number}vw|${number}vh|${number}vmin|${number}vmax|${number}%|${number}ch|${number}cm|${number}mm|${number}in|${number}ex|${number}pc|${number...`	No	"40rem"	-
hide-close-button	Remove the close button in the header	boolean	No	false	-
hide-header	Remove the whole header	boolean	No	false	-
padding	Add the padding on the content area	boolean	No	true	-
persistent	Persistent bottom sheet (not closable by clicking outside and remove close button) Persistent dialog (not closable by clicking outside and remove close button)	boolean	No	-	-
swipe-to-close	Show the drag handle at the top and allow closing the sheet by swiping it down (iOS-like). The swipe never closes a persistent sheet (it snaps back instead).	boolean	No	true	-
teleport-selector	Teleport selector	string	No	-	-
before-close	Function called before modal is close	(() => void | Promise<void>)	No	-	-
close-on-escape	Prevent close on escape key	boolean	No	true	-
transition-name	Transition name	string	No	-	-
backdrop-class	Backdrop class	ClassValue	No	-	-
backdrop-content-class	Backdrop content class	ClassValue	No	-	-
content-padding	Add padding to the content	boolean	No	-	-
justify	Justify content	"none" | "center" | "end" | "start" | "space-between" | "space-around"	No	-	'none' | 'center' | 'end' | 'start' | 'space-between' | 'space-around'
align	Align content	"none" | "center" | "end" | "start"	No	-	'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 the model value is updated
open	value?: void | undefined	Emitted when the component is opened
close	value?: void | undefined	Emitted when the component is closed

Slots

Name	Description	Bindings
handle	Drag handle (grab bar) displayed at the top when swipeToClose is enabled	-
header	Header slot	close () => void - close function
icon	Icon slot in the header	-
title	Title slot in the header	-
default	Default content	close () => void - close function
footer	Footer slot	close () => void - close function

Expose

close

Close the bottom sheet