@balalarast/vue-bottom-sheet

@balalarast/vue-bottom-sheet

Bottom Sheet component for Vue 3, Nuxt 3, and Nuxt 4 with drag support, multiple snap points, and dark mode.
Built with @oku-ui/motion for smooth and performant animations.

Table of Contents

• Compatibility
• Features
• Demo
• Install
• Usage in Vue 3
  • 1. Registering the Component Globally (Recommended)
  • 2. Direct Import in Components
• Usage in Nuxt 3 & Nuxt 4
  • 1. Using Nuxt Module (Recommended)
  • 2. Registering the Component in Plugins
  • 3. Direct Import in Components
• Props and Configuration
• Exposed Methods & Properties
• Events
• Styling guide
• Running Playground
• Running Tests

Compatibility

This package is fully compatible with:

• Vue 3
• Nuxt 3
• Nuxt 4

Features

• Smooth open and close animations powered by @oku-ui/motion
• Support for multiple snap points (percentage and pixel values)
• Drag support with adjustable panel height
• Dark mode support
• Prevent pull-to-refresh on mobile devices
• Ability to use teleport for rendering in custom locations

Demo

You can try the live demo here:

👉 Live Demo in vercel
👉 Live Demo in CodeSandbox
👉 Open in CodeSandbox

Install

npm install @balalarast/vue-bottom-sheet
# or
yarn add @balalarast/vue-bottom-sheet

Usage in Vue 3

1. Registering the Component Globally (Recommended)

If you prefer to register the component globally, create a file like plugins/bottom-sheet.ts and register it:

import { createApp } from 'vue'
import BottomSheet from '@balalarast/vue-bottom-sheet'

export default (app: ReturnType<typeof createApp>) => {
  app.component('BottomSheet', BottomSheet)
}

Then you can use it in any component without importing:

<script setup lang="ts">
import { ref } from 'vue'

const sheetRef = ref(null)

function openSheet() {
  sheetRef.value?.open()
}
</script>

<template>
  <button @click="openSheet">Open Bottom Sheet</button>
  <BottomSheet ref="sheetRef" />
</template>

2. Direct Import in Components

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

const sheetRef = ref<InstanceType<typeof BottomSheet>>()

function openSheet() {
  sheetRef.value?.open()
}
</script>

<template>
  <button @click="openSheet">Open Bottom Sheet</button>
  <BottomSheet ref="sheetRef" />
</template>

Usage in Nuxt 3 & Nuxt 4

You can use any one of the following methods — choose the one that best fits your project setup.

1. Using Nuxt Module (Recommended)

If you have enabled the Nuxt module, make sure to add it in your nuxt.config.ts like this so that the component is automatically available throughout your project:

export default defineNuxtConfig({
  modules: [
    '@balalarast/vue-bottom-sheet/nuxt'
  ],
})

Using the Component in Your Vue Files:

<script setup lang="ts">
const sheetRef = ref(null)

function openSheet() {
  sheetRef.value?.open()
}
</script>

<template>
  <button @click="openSheet">Open Bottom Sheet</button>
  <BottomSheet ref="sheetRef" />
</template>

2. Registering the Component in Plugins

If you prefer manual registration, you can create a Nuxt plugin file (e.g., plugins/bottom-sheet.client.ts) and register the BottomSheet component globally. This way, the component will be available in all your Vue components without the need to import it individually.

import { defineNuxtPlugin } from '#app'
import BottomSheet from '@balalarast/vue-bottom-sheet'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.component('BottomSheet', BottomSheet)
})

Using the Component in Your Vue Files:

<script setup lang="ts">
const sheetRef = ref(null)

function openSheet() {
  sheetRef.value?.open()
}
</script>

<template>
  <button @click="openSheet">Open Bottom Sheet</button>
  <BottomSheet ref="sheetRef" />
</template>

3. Direct Import in Components

You can import and use the component directly inside your components:

<script setup lang="ts">
import BottomSheet from '@balalarast/vue-bottom-sheet'

const sheetRef = ref<InstanceType<typeof BottomSheet>>()

function openSheet() {
  sheetRef.value?.open()
}
</script>

<template>
  <button @click="openSheet">Open Bottom Sheet</button>
  <BottomSheet ref="sheetRef" />
</template>

Props and Configuration

Exposed Methods & Properties

This component exposes several methods and properties via ref so you can control it programmatically.

<script setup lang="ts">
import BottomSheet from '@balalarast/vue-bottom-sheet'
const sheetRef = ref<InstanceType<typeof BottomSheet>>()

function openSheet() {
  sheetRef.value?.open()
}

function closeSheet() {
  sheetRef.value?.close()
}

function goToSecondSnap() {
  sheetRef.value?.snapToPoint(1)
}

onMounted(() => {
  openSheet()
})
</script>

<template>
  <button @click="openSheet">Open</button>
  <button @click="closeSheet">Close</button>
  <button @click="goToSecondSnap">Go to 60%</button>

  <BottomSheet ref="sheetRef">
    <p>Your content here...</p>
  </BottomSheet>
</template>

Events

<script setup lang="ts">
import BottomSheet from '@balalarast/vue-bottom-sheet'
const sheetRef = ref<InstanceType<typeof BottomSheet>>()

function openSheet() {
  sheetRef.value?.open()
}

function closeSheet() {
  sheetRef.value?.close()
}

// Events
function handleOpen() {
  console.log('Bottom Sheet opened')
}

function handleClose() {
  console.log('Bottom Sheet closed')
}

function handleSnapChange(snapIndex: number) {
  console.log('Snap changed to index:', snapIndex)
}

function handleDragStart() {
  console.log('Drag started')
}

function handleDragEnd(finalIndex: number) {
  console.log('Drag ended at index:', finalIndex)
}
</script>

<template>
  <div class="p-4 space-x-2">
    <button @click="openSheet">Open</button>
    <button @click="closeSheet">Close</button>
  </div>

  <BottomSheet
    ref="sheetRef"
    :snap-points="[100, 300, '100%']"
    initial-snap-point="1"
    @open="handleOpen"
    @close="handleClose"
    @snapChange="handleSnapChange"
    @dragStart="handleDragStart"
    @dragEnd="handleDragEnd"
    @vue:mounted="openSheet"
  >
    <div>
      <h2>Bottom Sheet Content</h2>
      <p>This is some content inside the bottom sheet.</p>
    </div>
  </BottomSheet>
</template>

Styling guide

Running Playground

You can run the playground to try out the component locally and see examples in action.

1. Install Dependencies

npm install

2. Run Playground in Development Mode

npm run dev

This will start a local Nuxt server for the playground folder and you can open it in your browser (usually at http://localhost:3000).

3. Build Playground

npm run build

This will build the playground for development preview.

4. Generate Static Playground (Optional)

npm run generate

This will generate a static version of the playground that can be deployed anywhere.

Running Tests

The project uses Vitest for testing.

Install Dependencies

npm install

Run Tests

npm run test

Running Tests in Watch Mode

npm run test:watch

Running Tests with Graphical User Interface (UI)

npm run test:ui

Running this command will open the Vitest graphical interface in your browser, allowing you to manage tests interactively.

If you have any questions or need further assistance, I’m here to help!