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
| Param | Type | Default | Description |
|---|---|---|---|
active | boolean | — | 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%') |
snap | number | — | Controlled index into snapPoints |
defaultSnap | number | 0 | Initial index into snapPoints when uncontrolled |
onSnapChange | (index: number) => void | — | Called when the sheet settles on another snap point |
dismissible | boolean | — | 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
| Field | Type | Description |
|---|---|---|
height | number | undefined | The sheet height in px: the live height while dragging, otherwise the current snap height. Set it as the sheet's height |
snapIndex | number | The current index into snapPoints |
atTop | boolean | Whether the sheet is at its highest snap point. Useful to only let the content scroll once the sheet is fully open |
dragging | boolean | Whether a drag is in progress. Turn off height transitions while it is true |
handleProps | object | Spread 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
| Input | Behavior |
|---|---|
ArrowUp / ArrowDown on the handle | Next higher / lower snap point |
| Click on the handle | Next snap point, cycling back to the lowest from the top |
| Drag | Follows 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 point | Dismisses 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.
heightuses the real viewport height from the first render after opening. It is0when rendered on the server and while hydrating, andundefinedwhensnapPointsis empty.