Vaul Vue Unstyled Drawer

0.4.1 · active · verified Sun Apr 19

Vaul Vue is an unstyled, headless drawer component specifically designed for Vue 3 applications, serving as a modern and highly customizable replacement for traditional dialogs and modals, particularly optimized for tablet and mobile devices. It stands at version 0.4.1 and demonstrates an active development cadence with frequent patch releases addressing bug fixes and occasional minor releases introducing new features or significant architectural refactorings. This library is a feature-complete port of Emil Kowalski's original Vaul library, which was built for React, ensuring a mature and well-tested interaction model. Under the hood, Vaul Vue leverages Reka UI's Dialog primitive, providing a robust foundation for accessibility and core interaction logic. Its unstyled nature is a key differentiator, granting developers complete control over the visual presentation to seamlessly integrate with any design system. The headless architecture ensures that essential accessibility features are provided out-of-the-box, without dictating styling. Key features include highly customizable snap points, support for various drag directions, and a comprehensive set of primitives (`DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`) that enable building bespoke drawer experiences tailored to specific application needs, making it a powerful tool for responsive web design.

Common errors

```
CSS styles are not applying to my Vaul drawer component.
```
cause The default styles for Vaul Vue need to be explicitly imported as of version 0.4.0.

fix Add `import 'vaul-vue/dist/style.css'` to your main application file or component.
```
My custom `vaul-*` data attributes are no longer working or applying styles.
```
cause In v0.4.0, data attributes were refactored from `[vaul-*]` to `[data-vaul-*]` for improved compliance and CSP compatibility.

fix Update your HTML and CSS to use `data-vaul-*` attributes instead of `vaul-*` (e.g., `data-vaul-drawer` instead of `vaul-drawer`).
```
Clicking on the drawer overlay doesn't close the drawer, or body scrolling is still disabled after closing.
```
cause Earlier versions (before 0.4.1) had known bugs related to overlay dismissal and body style persistence.

fix Upgrade to `vaul-vue@0.4.1` or a newer version to benefit from the fixes.
```
TypeError: Cannot read properties of undefined (reading 'setup') or similar errors related to Radix Vue components after upgrading.
```
cause Version 0.3.0 broke compatibility with Radix Vue components by migrating to Reka UI primitives. Your application might still be trying to use Radix Vue components or expecting their API.

fix Remove any lingering Radix Vue imports or usage that were previously tied to Vaul Vue. Ensure you are only using the `vaul-vue` components which now internally rely on Reka UI, or follow Reka UI's documentation for direct primitive usage.

Warnings

breaking The underlying primitive library for Vaul Vue migrated from Radix Vue to Reka UI. This change occurred in v0.3.0 and may require updating component imports or props if directly interacting with the underlying primitives.
Fix: Review the Reka UI documentation for Dialog primitives and update your component usage accordingly. The public API of Vaul Vue components should mostly remain consistent, but direct primitive usage will need adjustment.
breaking Data attributes used for styling and interaction changed from `[vaul-*]` to `[data-vaul-*]` for better web standards compliance and CSP header compatibility. This affects direct CSS targeting and any manual interaction with these attributes.
Fix: Update all CSS selectors and JavaScript code that targets `vaul-*` attributes to use `data-vaul-*` instead (e.g., `[vaul-drawer]` becomes `[data-vaul-drawer]`).
gotcha As of v0.4.0, default styles are no longer automatically included and must be explicitly imported from `vaul-vue/dist/style.css`. Failing to do so will result in an unstyled and potentially non-functional drawer.
Fix: Add `import 'vaul-vue/dist/style.css'` to your main application entry file or directly within the component where Vaul Vue is used.
gotcha Before v0.4.1, there were issues where the `<body>` element's styles (e.g., overflow) might persist after the drawer unmounted, and clicking the overlay might not dismiss the drawer as expected.
Fix: Upgrade to `vaul-vue@0.4.1` or later to resolve these issues.

Install

npm install vaul-vue npm
yarn add vaul-vue yarn
pnpm add vaul-vue pnpm

Imports

{ DrawerRoot, DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent }
wrong:
```
const { DrawerRoot } = require('vaul-vue')
```
correct:
```
import { DrawerRoot, DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent } from 'vaul-vue'
```
Vaul Vue is an ESM-first library primarily used in Vue 3 projects. CommonJS 'require' is not supported.
CSS Styles
```
import 'vaul-vue/dist/style.css'
```
As of v0.4.0, default styles are shipped as a separate CSS file. You must explicitly import this file for basic functionality or provide your own complete styles. Failing to import will result in an unstyled and potentially non-functional drawer.

Quickstart

Demonstrates a basic Vaul Vue drawer with snap points, custom styling (using Tailwind-like classes), and a trigger button, including the necessary CSS import.

<script setup lang="ts">
import { DrawerContent, DrawerOverlay, DrawerPortal, DrawerRoot, DrawerTrigger } from 'vaul-vue'
import 'vaul-vue/dist/style.css' // Important: import Vaul Vue's default styles
</script>

<template>
  <DrawerRoot :snap-points="[0.5, 0.8]" :open="true"> <!-- Added :open for demonstration -->
    <DrawerTrigger as-child>
      <button class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">Open Drawer</button>
    </DrawerTrigger>
    <DrawerPortal>
      <!-- Overlay for background dimming when drawer is open -->
      <DrawerOverlay class="fixed inset-0 bg-black/40 z-40" />
      <DrawerContent class="bg-white flex flex-col rounded-t-[10px] h-full mt-24 fixed bottom-0 left-0 right-0 max-h-[96%] max-w-md mx-auto z-50">
        <div class="mx-auto w-12 h-1.5 flex-shrink-0 rounded-full bg-gray-300 my-3" />
        <div class="flex-1 p-4 overflow-y-auto">
          <h2 class="text-xl font-semibold text-gray-800 mb-2">Welcome to Vaul Vue!</h2>
          <p class="text-gray-700 leading-relaxed">
            This is an unstyled, headless drawer component for Vue 3. It's designed to be a flexible
            and accessible replacement for dialogs and modals on mobile and tablet devices.
            You can drag it up or down to adjust its position or dismiss it.
            It uses <a href="https://www.reka-ui.com/docs/components/dialog" target="_blank" class="text-blue-600 hover:underline">Reka UI's Dialog primitive</a>
            under the hood for robust accessibility.
          </p>
          <p class="text-gray-700 leading-relaxed mt-4">
            Feel free to customize all aspects of its appearance with your own CSS or utility classes.
            The `snap-points` prop allows you to define specific heights where the drawer can rest.
          </p>
          <div class="mt-8">
            <h3 class="font-medium text-gray-800 mb-2">Key Features:</h3>
            <ul class="list-disc list-inside text-gray-700">
              <li>Unstyled & Headless</li>
              <li>Mobile-first interaction</li>
              <li>Customizable snap points</li>
              <li>Uses Reka UI for accessibility</li>
            </ul>
          </div>
          <p class="text-gray-500 text-sm mt-8">Drag this drawer down to close it, or click the overlay.</p>
        </div>
        <div class="border-t border-gray-200 p-4 flex justify-end">
          <button class="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600">Close Drawer</button>
        </div>
      </DrawerContent>
    </DrawerPortal>
  </DrawerRoot>
</template>

view raw JSON →