---
title: "MazBottomSheet"
description: "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."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-bottom-sheet"
---

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

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

> 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 the `<Teleport to="body">` with [MazBackdrop](./maz-backdrop.md), 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).

```vue
<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.

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

```html
<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).

```html
<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.

```html
<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`.

```html
<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.

```html
<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

```vue
<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).

## MazBottomSheet API

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

### Props

- `model-value` (`boolean`, `v-model`): Modal's model value.
- `title` (`string`): Title of the bottom sheet in the header.
- `icon` (`MazIconLike`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
- `max-width` (`` `${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... ``, default: `"40rem"`): Bottom sheet's max-width, applied from the tablet breakpoint and up (full-width below).
- `hide-close-button` (`boolean`, default: `false`): Remove the close button in the header.
- `hide-header` (`boolean`, default: `false`): Remove the whole header.
- `padding` (`boolean`, default: `true`): Add the padding on the content area.
- `persistent` (`boolean`): Persistent bottom sheet (not closable by clicking outside and remove close button) Persistent dialog (not closable by clicking outside and remove close button).
- `swipe-to-close` (`boolean`, default: `true`): 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).
- `teleport-selector` (`string`): Teleport selector.
- `before-close` (`(() => void | Promise<void>)`): Function called before modal is close.
- `close-on-escape` (`boolean`, default: `true`): Prevent close on escape key.
- `transition-name` (`string`): Transition name.
- `backdrop-class` (`ClassValue`): Backdrop class.
- `backdrop-content-class` (`ClassValue`): Backdrop content class.
- `content-padding` (`boolean`): Add padding to the content.
- `justify` (`"none" | "center" | "end" | "start" | "space-between" | "space-around"`): Justify content.
- `align` (`"none" | "center" | "end" | "start"`): 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 the model value is updated
- `@open` (payload: `value?: void | undefined`): Emitted when the component is opened
- `@close` (payload: `value?: void | undefined`): Emitted when the component is closed

### Slots

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

### Exposed (template ref)

- `close`: Close the bottom sheet