Vaul

https://vaul.emilkowal.ski/
Admin
Vaul is a drawer component designed for React applications, providing a customizable and accessible...
Tokens:3,340
Snippets:24
Trust Score:8.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Vaul Drawer Component

Source: https://vaul.emilkowal.ski/getting-started

Installs the Vaul drawer component using pnpm. This is the initial step to integrate the component into a React project.

```bash
pnpm i vaul
```

--------------------------------

### Default Vaul Drawer Setup

Source: https://vaul.emilkowal.ski/default

Demonstrates the most basic configuration for a Vaul Drawer. No specific dependencies are required beyond the Vaul library itself. The output is a functional drawer that can be opened and closed.

```javascript
import * as React from "react"
import { Drawer } from "vaul-react-ui"

function App() {
  return (
    <Drawer>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.Title>Drawer Title</Drawer.Title>
        <Drawer.Description>Drawer Description</Drawer.Description>
      </Drawer.Content>
    </Drawer>
  )
}
```

--------------------------------

### Create a Basic Vaul Drawer Component in React

Source: https://vaul.emilkowal.ski/getting-started

Demonstrates how to create a simple drawer component using Vaul in a React application. It includes the necessary imports and JSX structure for a functional drawer with a trigger and content.

```typescript
'use client';
 
import { Drawer } from 'vaul';
 
export default function VaulDrawer() {
  return (
    <Drawer.Root>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Overlay className="fixed inset-0 bg-black/40" />
        <Drawer.Content className="bg-gray-100 h-fit fixed bottom-0 left-0 right-0 outline-none">
          <div className="p-4 bg-white">{/* Content */}</div>
        </Drawer.Content>
      </Drawer.Portal>
    </Drawer.Root>
  );
}
```

--------------------------------

### Create Dynamic Drawer with Vaul

Source: https://vaul.emilkowal.ski/other

Example demonstrating the recreation of a 'Family drawer' using Vaul. This showcases how to build dynamic drawer components for interactive UIs.

```javascript
import { Drawer } from "vaul-ui";

function FamilyDrawer() {
  return (
    <Drawer.Root>
      <Drawer.Trigger asChild>
        <button>Open Drawer</button>
      </Drawer.Trigger>
      <Drawer.Content>
        <div className="p-4">
          <h2 className="text-lg font-semibold">Family Drawer</h2>
          {/* Dynamic content related to family */}
          <p>This is a dynamic drawer example.</p>
        </div>
      </Drawer.Content>
    </Drawer.Root>
  );
}

export default FamilyDrawer;

```

--------------------------------

### Nested Vaul Drawers

Source: https://vaul.emilkowal.ski/default

Shows how to implement nested drawers within each other. This allows for multi-layered user interfaces where one drawer can trigger another. Ensure proper Vaul library integration.

```javascript
import * as React from "react"
import { Drawer } from "vaul-react-ui"

function App() {
  return (
    <Drawer>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.Title>Parent Drawer</Drawer.Title>
        <Drawer.Description>This is the parent drawer.</Drawer.Description>
        <Drawer>
          <Drawer.Trigger>Open Nested Drawer</Drawer.Trigger>
          <Drawer.Content>
            <Drawer.Title>Nested Drawer</Drawer.Title>
            <Drawer.Description>This is a nested drawer.</Drawer.Description>
          </Drawer.Content>
        </Drawer>
      </Drawer.Content>
    </Drawer>
  )
}
```

--------------------------------

### Scrollable Vaul Drawer Implementation

Source: https://vaul.emilkowal.ski/default

Demonstrates creating a scrollable Vaul Drawer, mimicking the behavior of Apple's Sheet component. This is useful for drawers containing a large amount of content. Requires Vaul library.

```javascript
import * as React from "react"
import { Drawer } from "vaul-react-ui"

function App() {
  return (
    <Drawer>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.Title>Scrollable Drawer</Drawer.Title>
        <Drawer.Description>Content goes here...</Drawer.Description>
        {/* Add enough content to make it scrollable */}
        <div style={{ height: '1000px', background: 'lightgray' }}>Scrollable Content</div>
      </Drawer.Content>
    </Drawer>
  )
}
```

--------------------------------

### Controlled Vaul Drawer

Source: https://vaul.emilkowal.ski/default

Explains how to programmatically control the open/closed state of a Vaul Drawer using the `open` prop. It also details the use of the `onOpenChange` prop to react to state changes, such as outside clicks or Esc key presses. Requires Vaul library.

```javascript
import * as React from "react"
import { Drawer } from "vaul-react-ui"

function App() {
  const [open, setOpen] = React.useState(false)

  return (
    <Drawer open={open} onOpenChange={setOpen}>
      <Drawer.Trigger onClick={() => setOpen(true)}>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.Title>Controlled Drawer</Drawer.Title>
        <Drawer.Description>This drawer is controlled programmatically.</Drawer.Description>
      </Drawer.Content>
    </Drawer>
  )
}
```

--------------------------------

### Custom Fade Index for Drawer

Source: https://vaul.emilkowal.ski/snap-points

Allows customization of the snap point index from which the drawer begins to fade using the `fadeFromIndex` prop. By default, fading starts from the last snap point. This example sets it to the second snap point (index 1).

```javascript
import { Drawer } from "vaul-react-ui";

function MyDrawer() {
  return (
    <Drawer.Root fadeFromIndex={1}>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.SnapPoint index={0} label="Start" />
        <Drawer.SnapPoint index={1} label="Fade Start" />
        <Drawer.SnapPoint index={2} label="End" />
      </Drawer.Content>
    </Drawer.Root>
  );
}
```

--------------------------------

### Import and Use Vaul Drawer Components (React)

Source: https://vaul.emilkowal.ski/api

Demonstrates how to import and assemble various Vaul drawer components in a React application. This snippet covers the basic structure for creating a functional drawer with its overlay, content, trigger, and close buttons. It assumes the Vaul library is installed and available.

```jsx
import { Drawer } from 'vaul';

export function MyDrawer() {
  return (
    <Drawer.Root>
      <Drawer.Trigger />
      <Drawer.Portal>
        <Drawer.Overlay />
        <Drawer.Content>
          <Drawer.Handle />
          <Drawer.Title />
          <Drawer.Description />
          <Drawer.Close />
        </Drawer.Content>
      </Drawer.Portal>
    </Drawer.Root>
  );
}
```

--------------------------------

### Side Vaul Drawer Positioning

Source: https://vaul.emilkowal.ski/default

Illustrates how to position a Vaul Drawer to the side (left or right) using the `direction` prop. It also shows how to customize the animation using the `--initial-transform` CSS variable for drawers not touching the screen edge. Requires Vaul library.

```javascript
import * as React from "react"
import { Drawer } from "vaul-react-ui"

function App() {
  return (
    <Drawer direction="left">
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content style={{ '--initial-transform': 'translateX(-100%)' }}>
        <Drawer.Title>Left Drawer</Drawer.Title>
        <Drawer.Description>This drawer is on the left.</Drawer.Description>
      </Drawer.Content>
    </Drawer>
  )
}
```

--------------------------------

### Open Drawer with Snap Points

Source: https://vaul.emilkowal.ski/snap-points

Demonstrates the basic usage of snap points to allow a drawer to rest in partially open states. No specific dependencies are required beyond the Vaul library itself. The output is a drawer that can be dragged and snapped to predefined positions.

```javascript
import { Drawer } from "vaul-react-ui";

function MyDrawer() {
  return (
    <Drawer.Root>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.SnapPoint index={0} label="Closed" />
        <Drawer.SnapPoint index={1} label="Partially Open" />
        <Drawer.SnapPoint index={2} label="Open" />
      </Drawer.Content>
    </Drawer.Root>
  );
}
```

--------------------------------

### Snap to Sequential Points

Source: https://vaul.emilkowal.ski/snap-points

Configures the drawer to snap to sequential points, ignoring velocity-based skipping, using the `snapToSequentialPoint` prop. This ensures that each defined snap point is visited in order, regardless of drag speed. Useful when the order of states is critical.

```javascript
import { Drawer } from "vaul-react-ui";

function MyDrawer() {
  return (
    <Drawer.Root snapToSequentialPoint={true}>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        <Drawer.SnapPoint index={0} label="First Step" />
        <Drawer.SnapPoint index={1} label="Second Step" />
        <Drawer.SnapPoint index={2} label="Third Step" />
      </Drawer.Content>
    </Drawer.Root>
  );
}
```

--------------------------------

### Content Component API

Source: https://vaul.emilkowal.ski/api

API for the Content component, which contains the content to be rendered in the open drawer.

```APIDOC
## Content Component API

### Description
Contains content to be rendered in the open drawer.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Handle Component API

Source: https://vaul.emilkowal.ski/api

API for the Handle component, an optional handle to drag the drawer.

```APIDOC
## Handle Component API

### Description
An optional handle to drag the drawer.

### Props
No Props.
```

--------------------------------

### Description Component API

Source: https://vaul.emilkowal.ski/api

API for the Description component, an optional accessible description to be announced when the drawer is opened.

```APIDOC
## Description Component API

### Description
An optional accessible description to be announced when the drawer is opened.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Portal Component API

Source: https://vaul.emilkowal.ski/api

API for the Portal component. When used, it portals your overlay and content parts into the `body`.

```APIDOC
## Portal Component API

### Description
When used, portals your overlay and content parts into the `body`.

### Props
No props.
```

--------------------------------

### Interact with Background while Drawer is Open

Source: https://vaul.emilkowal.ski/snap-points

Shows how to enable interaction with the content behind an open drawer by setting `modal={false}`. This is useful for drawers that overlay content but should not block user interaction with that content. Requires the Vaul Drawer component.

```javascript
import { Drawer } from "vaul-react-ui";

function MyDrawer() {
  return (
    <Drawer.Root modal={false}>
      <Drawer.Trigger>Open Drawer</Drawer.Trigger>
      <Drawer.Content>
        {/* Drawer content */}
      </Drawer.Content>
    </Drawer.Root>
  );
}
```

--------------------------------

### Overlay Component API

Source: https://vaul.emilkowal.ski/api

API for the Overlay component, which creates a layer that covers the inert portion of the view when the drawer is open.

```APIDOC
## Overlay Component API

### Description
A layer that covers the inert portion of the view when the drawer is open.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Root Component API

Source: https://vaul.emilkowal.ski/api

API for the Root component, which contains all parts of a drawer. It accepts various props to control its behavior and appearance.

```APIDOC
## Root Component API

### Description
Contains all the parts of a drawer. Accepts props to control its behavior and appearance.

### Props

#### Main Props
- **defaultOpen** (boolean) - Default: `-`
- **open** (boolean) - Default: `-`
- **onOpenChange** (function) - Default: `-`
- **modal** (boolean) - Default: `true`
- **container** (HTMLElement) - Default: `document.body`
- **direction** (directionType) - Default: `bottom`
- **onAnimationEnd** (function) - Default: `-`
- **dismissible** (boolean) - Default: `true`
- **handleOnly** (boolean) - Default: `false`
- **repositionInputs** (boolean) - Default: `true`

#### Snap Points Props
- **snapPoints** (array) - Default: `-`
- **activeSnapPoint** (boolean) - Default: `-`
- **setActiveSnapPoint** (function) - Default: `-`
- **fadeFromIndex** (number) - Default: `-`
- **snapToSequentialPoint** (boolean) - Default: `-`
```

--------------------------------

### Trigger Component API

Source: https://vaul.emilkowal.ski/api

API for the Trigger component, which acts as the button that opens the drawer.

```APIDOC
## Trigger Component API

### Description
The button that opens the drawer.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Title Component API

Source: https://vaul.emilkowal.ski/api

API for the Title component, an optional accessible title to be announced when the drawer is opened.

```APIDOC
## Title Component API

### Description
An optional accessible title to be announced when the drawer is opened.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Configure Non-Modal Drawer with Vaul

Source: https://vaul.emilkowal.ski/other

Set the `modal` prop to `false` to allow interaction with the background while the drawer is open. This can be useful for certain UI patterns where background interaction is desired.

```javascript
import { Drawer } from "vaul-ui";

function App() {
  return (
    <Drawer.Root>
      <Drawer.Trigger asChild>
        <button>Open Drawer</button>
      </Drawer.Trigger>
      <Drawer.Content>
        {/* Drawer content */}
      </Drawer.Content>
    </Drawer.Root>
  );
}

// To make it non-modal:
function NonModalApp() {
  return (
    <Drawer.Root modal={false}>
      <Drawer.Trigger asChild>
        <button>Open Drawer</button>
      </Drawer.Trigger>
      <Drawer.Content>
        {/* Drawer content */}
      </Drawer.Content>
    </Drawer.Root>
  );
}

```

--------------------------------

### Close Component API

Source: https://vaul.emilkowal.ski/api

API for the Close component, which acts as the button to close the drawer.

```APIDOC
## Close Component API

### Description
The button that closes the drawer.

### Props
- **asChild** (boolean) - Default: `false`
```

--------------------------------

### Configure Non-Dismissible Drawer with Vaul

Source: https://vaul.emilkowal.ski/other

Set the `dismissible` prop to `false` to prevent the user from closing the drawer by clicking outside of it, pressing the escape key, or dragging it down. Use with caution as it may require a page refresh to close.

```javascript
import { Drawer } from "vaul-ui";

function App() {
  return (
    <Drawer.Root>
      <Drawer.Trigger asChild>
        <button>Open Drawer</button>
      </Drawer.Trigger>
      <Drawer.Content>
        {/* Drawer content */}
      </Drawer.Content>
    </Drawer.Root>
  );
}

// To make it non-dismissible:
function NonDismissibleApp() {
  return (
    <Drawer.Root dismissible={false}>
      <Drawer.Trigger asChild>
        <button>Open Drawer</button>
      </Drawer.Trigger>
      <Drawer.Content>
        {/* Drawer content */}
      </Drawer.Content>
    </Drawer.Root>
  );
}

```
Tokens:
Raw