hooks/use-drag

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

use-drag hook overview

The use-drag hook handles pointer drag gestures over an element. It tracks movement, velocity, direction and supports axis constraints, threshold activation and tap detection. The hook uses the Pointer Events API and works with both mouse and touch input.

use-drag axis constraint options

Use the axis option to constrain movement to a single axis. Set axis to 'x' or 'y' for a fixed constraint, or 'lock' to lock to whichever axis has more movement after axisThreshold is exceeded.

use-drag filterTaps for tap detection

When filterTaps is enabled, the last state includes a tap property that is true when the total distance is below tapThreshold (default 3px). Combined with threshold, this lets you distinguish clicks from drags on the same element.

use-drag swipe to dismiss pattern

Use movement and velocity on the last event to decide whether to dismiss an item. This pattern works well for notifications.

use-drag drag to scroll pattern

Apply delta to a container's scrollLeft to create a drag-to-scroll interaction.

use-drag touch support with Pointer Events API

The hook uses the Pointer Events API which handles both mouse and touch automatically. For touch devices, set touch-action: none on the draggable element to prevent the browser from interpreting touch drag as scroll. If you want to allow scrolling on one axis while dragging on the other (e.g. horizontal drag with vertical scroll), use touch-action: pan-y or touch-action: pan-x.

UseDragState interface

The UseDragState interface contains the following properties: xy (Vector2, current pointer position), initial (Vector2, position where the gesture started), movement (Vector2, displacement from start, respects axis constraint), delta (Vector2, change since previous event), distance (Vector2, absolute distance per axis), direction (Vector2, movement direction per axis: -1, 0 or 1), velocity (Vector2, speed per axis in px/ms), elapsedTime (number, time since drag started in ms), first (boolean, true on the first handler call), last (boolean, true on the last handler call when pointer released or canceled), active (boolean, true while the gesture is ongoing), tap (boolean, true when the gesture qualifies as a tap, requires filterTaps), canceled (boolean, true when the gesture was interrupted by a pointercancel event), cancel (function, programmatically cancel the current gesture), and event (PointerEvent, the source pointer event).

UseDragOptions interface

The UseDragOptions interface contains the following properties: axis (optional, 'x' | 'y' | 'lock', constrain movement to an axis, 'lock' locks to whichever axis has more movement), axisThreshold (optional number, movement in px to determine lock axis, default 1), filterTaps (optional boolean, enable tap detection on the last event, default false), tapThreshold (optional number, max displacement in px to be considered a tap, default 3), threshold (optional number or Vector2, min displacement before drag activates, default 0), and enabled (optional boolean, enable or disable the hook, default true).

UseDragReturnValue interface

The UseDragReturnValue interface contains the following properties: ref (React.RefCallback<T | null>, ref callback to attach to the target element) and active (boolean, true while a drag gesture is active).

useDrag function signature

The useDrag function is a generic function with type parameter T extends HTMLElement with default any. It takes two parameters: handler (required, function that receives UseDragState and returns void) and options (optional, UseDragOptions). It returns UseDragReturnValue<T>.

useDrag exported types

UseDragState, UseDragOptions and UseDragReturnValue types are exported from the @mantine/hooks package and can be imported as: import type { UseDragState, UseDragOptions, UseDragReturnValue } from '@mantine/hooks';

Give your agent this brain