Drawer

A drawer is a draggable dialog that is attached to any side of the viewport. It uses the Dialog primitive under the hood and adds dragging logic on top of it.

Features Section titled Features

• Attach to any side (top, right, bottom, left)
• Works with CSS transitions
• Custom snap- and breakpoints
• Handles scrollable content
• Customizable damping and velocity settings

Installation Section titled Installation

npm install @corvu/drawer

The drawer is also included in the main corvu package under corvu/drawer.

Usage Section titled Usage

import Drawer from '@corvu/drawer' // 'corvu/drawer'
// or
// import { Root, Trigger, ... } from '@corvu/drawer'

Anatomy Section titled Anatomy

<Drawer>
  <Drawer.Trigger />
  <Drawer.Portal>
    <Drawer.Overlay />
    <Drawer.Content>
      <Drawer.Close />
      <Drawer.Label />
      <Drawer.Description />
    </Drawer.Content>
  </Drawer.Portal>
</Drawer>

Every component besides the Root and Content components are just re-exports from the Dialog primitive. You can find more information about them in the Dialog documentation.

Animating the drawer Section titled Animating the drawer

The drawer content gets the data-transitioning data attribute applied when it is transitioning. Transitioning means that the drawer is either opening, closing or moving to a snap point after the user stops dragging.

Animation is done by applying CSS transition properties when the drawer is in this transitioning state. You can use any transition timing function, duration and delay you want. The drawer will automatically apply the data-transitioning attribute to the Content component for the duration of the transition and remove it when it is done.

A plain CSS example would look like this:

[data-corvu-dialog-content][data-transitioning] {
  transition-property: transform;
  transition-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
  transition-duration: 500ms;
}

corvu’s tailwind plugin also provides a corvu-transitioning modifier that you can use:

<Drawer.Content
  class="
    corvu-transitioning:transition-transform
    corvu-transitioning:duration-500
  "
>
</Drawer.Content>

Additionally, there are different data attributes applied depending on the current state of the drawer:

• data-opening: Present when the drawer is in the open transition.
• data-closing: Present when the drawer is in the close transition.
• data-snapping: Present when the drawer is transitioning after the user stops dragging.

This allows you to apply different transitions based on the transition state of the drawer.

You can also use the openPercentage property returned by the Drawer.useContext() or the root children callback and use it to animate the background for example:

<Drawer>
  {(props) => (
    <Drawer.Overlay
      class="fixed inset-0 z-40 corvu-transitioning:transition-colors corvu-transitioning:duration-500 corvu-transitioning:ease-[cubic-bezier(0.32,0.72,0,1)]"
      style={{
        'background-color': `rgb(0 0 0 / ${
          0.5 * props.openPercentage
        })`,
      }}
    />
  )}
</Drawer>

Snap- and breakpoints Section titled Snap- and breakpoints

The drawer root accepts a snapPoints array to customize the points to snap to. Valid values are either percentages or pixel values. The drawer will snap to the closest snap point when the user stops dragging (With the velocityFunction in mind. See the API Reference for more information)

<Drawer snapPoints={[0, 0.5, 1]}>
  ...
</Drawer>

Here, the drawer additionally snaps to 50% of its height.

Per default, the drawer will snap to the closest snap point. You can change this behavior by providing custom breakPoints to the root component:

<Drawer breakPoints={[0.75]}>
  ...
</Drawer>

Here, the drawer will close when the user drags below 75% of the drawer’s height.

Scrollable elements Section titled Scrollable elements

Scrollable elements work out of the box. The drawer will check if the user is dragging on a scrollable element and handle dragging properly.

Transitioning the content height Section titled Transitioning the content height

corvu’s drawer can handle height: auto and transition between heights when the content changes. This is possible by using a ResizeObserver to detect height changes and apply a fixed height for the time of the transition.

This is disabled by default and you need to set the transitionResize property on the root component to enable it. Also, remember to set transition-property: height on the drawer content ;).

Dynamic content height Section titled Dynamic content height

You might want the height of the drawer to adjust so its content is always fully visible no matter what snap point the user is on.

A common example would be a comment section which can be expanded:

To achieve this, you can use the props.openPercentage property and change the height of the drawer accordingly. Make sure to create a wrapper element inside Drawer.Content and not apply the height directly to the Content component, otherwise the drawer will not be able to calculate the correct height.

style={{
  height: `${
    props.openPercentage < 0.7
      ? 70
      : props.openPercentage * 100
  }%`,
}}

The height will adjust to match the drawer’s height until it’s under 70%, which is the last snap point. Don’t forget to apply the same transition function as you defined for your drawer transform and you’re good to go!

Disable dragging on certain elements Section titled Disable dragging on certain elements

You can disable drag on an element by giving it the data-corvu-no-drag attribute. corvu will ignore any drag events on elements with this attribute.

Persistent content Section titled Persistent content

To persist the content of the drawer even when it’s unmounted, you can use corvu’s createPersistent utility. It will cache the content when the drawer is opened for the first time and preserve its state and HTML elements.

const PersistedDrawerContent = () => {
  const persistedContent = createPersistent(() => {
    return <input />
  })

  return (
  <Drawer>
      <Drawer.Trigger>
        Open
      </Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Content>
          {persistedContent()}
        </Drawer.Content>
      </Drawer.Portal>
    </Drawer>
  )
}

Give it a try! 🐦‍⬛

Accessibility Section titled Accessibility

Adheres to the Dialog WAI-ARIA design pattern and Alert Dialog WAI-ARIA design pattern.

API reference Section titled API reference

Only components which are specific to the drawer are documented here. For all other components, please refer to the Dialog API reference.

The dialog context is re-exported as Drawer.useDialogContext and the root children callback also accepts all props of the dialog root callback function, which are documented in the Dialog API reference.

type Side = 'top' | 'right' | 'bottom' | 'left'

type Size = `${number}px` | number