vaul

library1.1.2jsnpmunverified

Vaul is an unstyled, performant drawer component specifically designed for React applications, intended as an alternative or replacement for traditional dialogs on mobile and tablet devices. Its current stable version is 1.1.2. The library exhibits a relatively frequent release cadence, primarily focusing on bug fixes and minor feature enhancements, as seen in the progression from v0.9.x to v1.1.x. A key differentiator is its unstyled nature, providing maximum flexibility for developers to implement custom styling (e.g., with Tailwind CSS), and its emphasis on mobile-first interaction patterns, including draggable behavior, customizable snap points, and optional background scaling effects. It integrates smoothly with modern React workflows, shipping with TypeScript types and built upon Radix UI primitives for accessibility.

web-framework

npm install vaul

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VAUL

vaul

web-frameworkjavascriptv1.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Drawer

✓ import { Drawer } from 'vaul'

✗ const Drawer = require('vaul')

Vaul is an ESM-first library. Direct CommonJS `require` is not the idiomatic way to import.

Drawer.Root

✓ import { Drawer } from 'vaul'; <Drawer.Root>...</Drawer.Root>

✗ import { Root } from 'vaul'; <Root>...</Root>

The main component is `Drawer`, which exposes sub-components like `Root`, `Trigger`, `Content`, `Overlay`, and `Portal` as properties.

Drawer.Portal

✓ import { Drawer } from 'vaul'; <Drawer.Portal>...</Drawer.Portal>

Used to portal the drawer's content and overlay to the document body, ensuring correct stacking context. No props are passed to `Portal` itself.

Demonstrates a basic Vaul drawer with a trigger, overlay, content, title, and close button, styled minimally with Tailwind CSS classes.

import { Drawer } from 'vaul'; function MyComponent() { return ( <Drawer.Root> <Drawer.Trigger asChild> <button>Open Drawer</button> </Drawer.Trigger> <Drawer.Portal> <Drawer.Overlay className="fixed inset-0 bg-black/40" /> <Drawer.Content className="bg-zinc-100 flex flex-col rounded-t-[10px] h-[96%] mt-24 fixed bottom-0 left-0 right-0"> <div className="mx-auto w-12 h-1.5 flex-shrink-0 rounded-full bg-zinc-300 mb-8" /> <Drawer.Title className="font-medium text-xl mb-4">My Drawer Title</Drawer.Title> <p className="text-zinc-600 mb-6">This is the content of my drawer.</p> <Drawer.Close asChild> <button className="bg-blue-500 text-white p-2 rounded">Close</button> </Drawer.Close> </Drawer.Content> </Drawer.Portal> </Drawer.Root> ); } export default MyComponent;

Debug

Known issues

breakingVersion 0.9.4 introduced a 'Major Refactor' which, while tested, might have introduced unforeseen issues. It's recommended to thoroughly test your application after upgrading from versions prior to 0.9.4.

fix

Review the changelog for v0.9.4 and subsequent minor versions for specific changes. Create a CodeSandbox reproduction if you encounter issues and report them to the maintainers.

affects: <0.9.4

breakingWhen using background scaling, the data attribute for the wrapper element changed from `[vaul-drawer-wrapper]` to `[data-vaul-drawer-wrapper]` in v0.9.3. While a backward-compatible fix was planned for v0.9.4, it's crucial to ensure the correct attribute is used.

fix

Update your HTML/JSX to use `data-vaul-drawer-wrapper` on the element intended for background scaling.

affects: >=0.9.3 <0.9.4

gotchaVaul relies on `peerDependencies` for `react` and `react-dom`. Installing with a React version outside the specified range (e.g., React 19 before official peer dependency updates in v1.1.1/1.1.2) can lead to 'A React Element from an older version of React was rendered' errors.

fix

Ensure your `react` and `react-dom` versions satisfy Vaul's peer dependency requirements. Upgrade Vaul to the latest version (v1.1.2+) for React 19 compatibility.

affects: <1.1.1

gotchaThe `noBodyStyles` and `setBackgroundColorOnScale` props were introduced in v0.9.1. If you were previously relying on Vaul's default body styling behavior, these new props might alter it. `setBackgroundColorOnScale` defaults to `true`.

fix

Explicitly set `noBodyStyles={false}` or `setBackgroundColorOnScale={true}` if you wish to retain the default styling behavior, or adjust your CSS accordingly if setting them to `true` or `false` respectively.

affects: >=0.9.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'Root')

The `Drawer` component or its sub-components are not being imported correctly, or the package failed to install properly.

fix

Ensure `import { Drawer } from 'vaul'` is at the top of your file. Verify `vaul` is listed in your `node_modules` and your bundler configuration is correct for ESM.

Error: A React Element from an older version of React was rendered. This is not supported.

This typically occurs when there are multiple copies of React in your project, or a dependency (like Vaul or one of its sub-dependencies) is bundling an incompatible React version. This was a common issue with React 19 previews and older Vaul versions.

fix

Ensure your project's React version is compatible with Vaul's `peerDependencies`. Upgrade Vaul to v1.1.1 or higher for React 19 support. Use `npm dedupe` or `yarn install --force` to resolve potential duplicate React installations.

Drawer is not draggable or responsive to touch events.

Conflicting global CSS, incorrect `direction` prop, or interacting with elements marked with `[data-vaul-no-drag]`.

fix

Check for CSS overrides on `body`, `html`, or elements within the drawer that might interfere with pointer events or `touch-action`. Ensure the `direction` prop on `Drawer.Root` matches your intended drag behavior. Avoid applying `data-vaul-no-drag` unnecessarily to interactive elements within the drawer.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

reactrequiredCore React library for component rendering and JSX. Required peer dependency.

react-domrequiredReactDOM for rendering React components to the DOM. Required peer dependency.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/emilkowalski/vaul ↗

packagehttps://www.npmjs.com/package/vaul ↗

homepagehttps://vaul.emilkowalski.com ↗