0
# Vaul
1

2
Vaul is an unstyled drawer component library for React that serves as a Dialog replacement optimized for tablet and mobile devices. It provides a comprehensive set of components that work together to create smooth, accessible drawer interfaces with advanced features like snap points, fade transitions, drag gestures with velocity-based animations, and accessibility support.
3

4
## Package Information
5

6
- **Package Name**: vaul
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vaul`
10
- **Optional CSS**: `style.css` available for basic styling
11

12
## Core Imports
13

14
```typescript
15
import { Drawer } from "vaul";
16
```
17

18
For TypeScript projects, you can also import individual types:
19

20
```typescript
21
import { 
22
  Drawer, 
23
  useDrawerContext,
24
  type DialogProps,
25
  type ContentProps,
26
  type HandleProps,
27
  type WithFadeFromProps,
28
  type WithoutFadeFromProps,
29
  type DrawerDirection,
30
  type DrawerContextValue
31
} from "vaul";
32
```
33

34
For CommonJS:
35

36
```javascript
37
const { Drawer } = require("vaul");
38
```
39

40
## Basic Usage
41

42
```typescript
43
import { Drawer } from "vaul";
44

45
function MyComponent() {
46
  return (
47
    <Drawer.Root>
48
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
49
      <Drawer.Portal>
50
        <Drawer.Overlay />
51
        <Drawer.Content>
52
          <Drawer.Handle />
53
          <Drawer.Title>Drawer Title</Drawer.Title>
54
          <Drawer.Description>Drawer content goes here.</Drawer.Description>
55
          <Drawer.Close>Close</Drawer.Close>
56
        </Drawer.Content>
57
      </Drawer.Portal>
58
    </Drawer.Root>
59
  );
60
}
61
```
62

63
## Architecture
64

65
Vaul is built around several key components:
66

67
- **Drawer Components**: A comprehensive set of composable components (`Root`, `Content`, `Overlay`, `Trigger`, etc.)
68
- **Radix UI Foundation**: Built on top of Radix UI's Dialog primitives for accessibility and behavior
69
- **Gesture System**: Advanced drag gesture handling with velocity-based animations and snap points
70
- **Mobile Optimization**: Position-fixed handling, scroll prevention, and mobile browser compatibility
71
- **Styling Flexibility**: Unstyled approach allowing complete customization while maintaining consistent behavior
72

73
## Capabilities
74

75
### Core Components
76

77
The fundamental drawer components that form the building blocks of any drawer interface.
78

79
```typescript { .api }
80
// Main root component that provides context and state management
81
interface Drawer.Root extends React.Component<DialogProps> {}
82

83
// Main drawer content container
84
interface Drawer.Content extends React.ForwardRefExoticComponent<ContentProps> {}
85

86
// Backdrop overlay component
87
interface Drawer.Overlay extends React.ForwardRefExoticComponent<React.ComponentProps<typeof DialogPrimitive.Overlay>> {}
88

89
// Button/element that triggers drawer open
90
interface Drawer.Trigger extends typeof DialogPrimitive.Trigger {}
91

92
// Portal component for rendering drawer outside normal DOM tree
93
interface Drawer.Portal extends React.Component<React.ComponentProps<typeof DialogPrimitive.Portal> & { container?: HTMLElement }> {}
94
```
95

96
[Core Components](./core-components.md)
97

98
### Interactive Components
99

100
Specialized components for drawer interaction and accessibility.
101

102
```typescript { .api }
103
// Draggable handle component for drawer interaction
104
interface Drawer.Handle extends React.ForwardRefExoticComponent<HandleProps> {}
105

106
// Element that closes the drawer when activated
107
interface Drawer.Close extends typeof DialogPrimitive.Close {}
108

109
// Accessible title element for drawer
110
interface Drawer.Title extends typeof DialogPrimitive.Title {}
111

112
// Accessible description element for drawer
113
interface Drawer.Description extends typeof DialogPrimitive.Description {}
114

115
// Special root component for nested drawers
116
interface Drawer.NestedRoot extends React.Component<DialogProps> {}
117
```
118

119
[Interactive Components](./interactive-components.md)
120

121
### Configuration & Types
122

123
Type definitions and interfaces for configuring drawer behavior.
124

125
```typescript { .api }
126
interface DialogProps {
127
  open?: boolean;
128
  onOpenChange?: (open: boolean) => void;
129
  defaultOpen?: boolean;
130
  children?: React.ReactNode;
131
  snapPoints?: (number | string)[];
132
  fadeFromIndex?: number;
133
  activeSnapPoint?: number | string | null;
134
  setActiveSnapPoint?: (snapPoint: number | string | null) => void;
135
  closeThreshold?: number;
136
  noBodyStyles?: boolean;
137
  shouldScaleBackground?: boolean;
138
  setBackgroundColorOnScale?: boolean;
139
  scrollLockTimeout?: number;
140
  fixed?: boolean;
141
  handleOnly?: boolean;
142
  dismissible?: boolean;
143
  onDrag?: (event: any, percentageDragged: number) => void;
144
  onRelease?: (event: any, open: boolean) => void;
145
  modal?: boolean;
146
  nested?: boolean;
147
  onClose?: () => void;
148
  direction?: 'top' | 'bottom' | 'left' | 'right';
149
  disablePreventScroll?: boolean;
150
  repositionInputs?: boolean;
151
  snapToSequentialPoint?: boolean;
152
  container?: HTMLElement | null;
153
  onAnimationEnd?: (open: boolean) => void;
154
  preventScrollRestoration?: boolean;
155
  autoFocus?: boolean;
156
}
157
```
158

159
[Configuration & Types](./configuration-types.md)
160

161
### Context & Hooks
162

163
Advanced context and hooks for building custom drawer components and accessing drawer state.
164

165
```typescript { .api }
166
// Hook to access drawer context from within drawer components
167
function useDrawerContext(): DrawerContextValue;
168

169
// Context value interface containing all drawer state and methods
170
interface DrawerContextValue {
171
  drawerRef: React.RefObject<HTMLDivElement>;
172
  overlayRef: React.RefObject<HTMLDivElement>;
173
  onPress: (event: React.PointerEvent<HTMLDivElement>) => void;
174
  onRelease: (event: React.PointerEvent<HTMLDivElement> | null) => void;
175
  onDrag: (event: React.PointerEvent<HTMLDivElement>) => void;
176
  dismissible: boolean;
177
  isOpen: boolean;
178
  isDragging: boolean;
179
  modal: boolean;
180
  shouldFade: boolean;
181
  activeSnapPoint?: number | string | null;
182
  setActiveSnapPoint: (snapPoint: number | string | null) => void;
183
  closeDrawer: () => void;
184
  direction: DrawerDirection;
185
  // ... additional properties for complete drawer state
186
}
187
```
188

189
See [Configuration & Types](./configuration-types.md) for complete context interface and usage examples.