UnflowUI
ComponentsHooks

useSheetDrag

Drag-to-resize for a bottom sheet that rests at snap points, with keyboard, click and flick support.

Overview

useSheetDrag gives a bottom sheet a drag handle. The sheet rests at a set of snap heights. Dragging the handle follows the pointer and settles on the nearest snap point when released, and a fast flick jumps to the next point in that direction. Arrow keys and clicks move between snap points too, and dragging below the lowest point can dismiss the sheet.

It is built for Modal with placement="bottomSheet" and snapPoints, and most apps should use that. Use the hook directly only when you build a custom sheet that can't be a Modal, for example a non-modal sheet that stays open alongside the page.

Import

import { useSheetDrag } from '@unflowio/ui/hooks/useSheetDrag';

Parameters

ParamTypeDefaultDescription
activeboolean—Required. Whether the sheet is showing. The viewport height is only tracked while it is, and opening resets an uncontrolled sheet to defaultSnap
snapPoints(number | string)[]—Required. Snap heights in px (320), or as a percentage of the viewport height ('40%')
snapnumber—Controlled index into snapPoints
defaultSnapnumber0Initial index into snapPoints when uncontrolled
onSnapChange(index: number) => void—Called when the sheet settles on another snap point
dismissibleboolean—Required. Lets a drag or flick below the lowest point call onDismiss
onDismiss() => void—Called when a drag dismisses the sheet

Indexes always refer to snapPoints in the order you pass them. Arrow keys, clicks and drags move between heights from lowest to highest whatever that order is. When two points resolve to the same height (e.g. '50%' and 400 on an 800px viewport), onSnapChange reports the first of them.

Return value

FieldTypeDescription
heightnumber | undefinedThe sheet height in px: the live height while dragging, otherwise the current snap height. Set it as the sheet's height
snapIndexnumberThe current index into snapPoints
atTopbooleanWhether the sheet is at its highest snap point. Useful to only let the content scroll once the sheet is fully open
draggingbooleanWhether a drag is in progress. Turn off height transitions while it is true
handlePropsobjectSpread on the handle <button>: onKeyDown, onClick and the pointer handlers

Usage

import { useSheetDrag } from '@unflowio/ui/hooks/useSheetDrag';

export function FiltersSheet({ open, onClose, children }: { open: boolean; onClose: () => void; children: React.ReactNode }) {
  const sheet = useSheetDrag({
    active: open,
    snapPoints: ['40%', '90%'],
    dismissible: true,
    onDismiss: onClose,
  });

  if (!open) {
    return null;
  }

  return (
    <section
      aria-label="Filters"
      className="fixed inset-x-0 bottom-0 flex flex-col rounded-t-xl bg-white shadow-lg"
      style={{ height: sheet.height, transition: sheet.dragging ? 'none' : 'height 200ms ease' }}
    >
      <button type="button" aria-label="Resize sheet" className="mx-auto my-2 h-1.5 w-10 touch-none rounded-full bg-grey-300" {...sheet.handleProps} />
      <div className={sheet.atTop ? 'overflow-y-auto' : 'overflow-hidden'}>{children}</div>
    </section>
  );
}

Give the handle touch-action: none (touch-none) so touch drags resize the sheet instead of scrolling the page.

Interaction

InputBehavior
ArrowUp / ArrowDown on the handleNext higher / lower snap point
Click on the handleNext snap point, cycling back to the lowest from the top
DragFollows the pointer after a 4 px threshold. On release, settles on the nearest snap point
Flick (faster than 0.5 px/ms)Next snap point in the flick direction. Flicking down from the lowest point dismisses when dismissible
Drag below half the lowest pointDismisses when dismissible, otherwise returns to the lowest point

A drag doesn't also trigger the click that follows it.

Accessibility

  • The handle must be a <button> with an accessible name (Modal uses "Resize sheet"), so keyboard and screen reader users can reach it and move between snap points with the arrow keys.
  • Dismissing by drag is a pointer shortcut. Always offer another way to close the sheet, such as a close button or Escape.
  • height uses the real viewport height from the first render after opening. It is 0 when rendered on the server and while hydrating, and undefined when snapPoints is empty.