vue-bottom-sheets

vue-bottom-sheets

Accessible, draggable bottom sheet component for Vue 3 with snap points — inspired by react-spring-bottom-sheet.

Installation

npm install vue-bottom-sheets
# or: pnpm add vue-bottom-sheets

Usage

<script setup lang="ts">
import { ref } from 'vue'
import { BottomSheet } from 'vue-bottom-sheet'

const open = ref(false)
</script>

<template>
  <button @click="open = true">Open</button>

  <BottomSheet v-model:open="open" aria-label="Example sheet">
    <template #header>
      <h2>Title</h2>
    </template>

    <p>Sheet content goes here.</p>

    <template #footer>
      <button @click="open = false">Close</button>
    </template>
  </BottomSheet>
</template>

Global registration (plugin)

import { createApp } from 'vue'
import VueBottomSheet from 'vue-bottom-sheets'

createApp(App).use(VueBottomSheet) // registers <BottomSheet> globally

Snap points

Provide a fixed array of pixel heights, or a function that computes them from the measured geometry:

<BottomSheet
  v-model:open="open"
  :snap-points="({ maxHeight, minHeight }) => [Math.min(minHeight, 120), maxHeight * 0.5, maxHeight - 40]"
  :default-snap="({ snapPoints }) => snapPoints[1]"
/>

The resolver receives { height, maxHeight, headerHeight, footerHeight, minHeight } (all in pixels).

Imperative API

<script setup lang="ts">
import { ref } from 'vue'
import { BottomSheet } from 'vue-bottom-sheet'

const sheet = ref<InstanceType<typeof BottomSheet> | null>(null)

// Jump to the tallest snap point.
function expand() {
  sheet.value?.snapTo(({ snapPoints }) => snapPoints[snapPoints.length - 1])
}
</script>

<template>
  <BottomSheet ref="sheet" v-model:open="open">…</BottomSheet>
</template>

Props

Events

Slots

Custom drag handle

By default the sheet renders its own handle strip. To make a consumer-supplied element the grab region instead — for example a header that already lives inside your content — set :handle="false" and spread the dragHandleProps slot prop onto that element:

<BottomSheet v-model:open="open" :handle="false">
  <template #default="{ dragHandleProps }">
    <!-- Your own header IS the drag handle; the ✕ still clicks. -->
    <header class="my-header" v-bind="dragHandleProps">
      <h2>Title</h2>
      <button @click="open = false">✕</button>
    </header>

    <p>Scrollable body…</p>
  </template>
</BottomSheet>

dragHandleProps wires up the pointer listeners and applies touch-action: none so the browser won't claim the touch for scrolling. A drag only begins once the pointer moves past a small threshold, so taps/clicks on buttons inside the handle still fire. The slot prop is also available on #header.

Theming

Pass a theme object — each key is optional and falls back to the default. Numeric keys (maxWidth, radius, transitionDuration, zIndex) also accept a plain number (px, px, ms, unitless):

<BottomSheet
  v-model:open="open"
  :theme="{
    radius: 24,
    background: '#111',
    color: '#fff',
    backdrop: 'rgba(0, 0, 0, 0.6)',
    handle: 'rgba(255, 255, 255, 0.3)',
  }"
/>

Prefer CSS? The same --vbs-* custom properties can be set on .vbs (or any ancestor) instead of using the prop. prefers-reduced-motion is respected automatically.

Development

pnpm install
pnpm dev          # run the playground at http://localhost:5173
pnpm test         # run unit tests
pnpm build        # type-check + build the library to dist/
pnpm lint         # lint & autofix

License

GPL-3.0-or-later © Pavel Sergienko