draggable

Make an element draggable with Pointer Events.


Package	`@vizejs/composable/draggable`
Own the source	`vize lib pull composable:draggable`
Runtime exports	`useDraggable`
Gzip budget	3840 B

Usage

import { useDraggable } from "@vizejs/composable/draggable";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useDraggable`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	—	`resolveElement`, `isElementNode`, `toPointerKind`, `tryOnScopeDispose`

API

`useDraggable`

Make an element draggable with Pointer Events. pointerdown on the handle records the offset between the pointer and the element; moves are tracked on the owner document (so fast drags that leave the element keep working) and constrained by axis and bounds. x/y are writable for programmatic placement. Server renders expose initialValue; listeners are removed with the owning reactive scope.

function useDraggable( target: MaybeElementTarget, options: UseDraggableOptions = {}, ): DraggableControls

Types

`DragBounds`

Rectangle (in the same coordinate space as the position) that bounds dragging.

Member	Type	Description
`left`	`number`	Minimum x.
`top`	`number`	Minimum y.
`right`	`number`	Maximum x of the dragged element's right edge.
`bottom`	`number`	Maximum y of the dragged element's bottom edge.

`UseDraggableOptions`

Options for useDraggable.

Member	Type	Description
`handle`?	`MaybeElementTarget`	Element that starts the drag. Defaults to the dragged element itself.
`axis`?	`MaybeRefOrGetter<DragAxis>`	Restrict movement to one axis.
`bounds`?	`MaybeRefOrGetter<DragBounds \| null \| undefined> \| MaybeElementTarget`	Keep the element inside these bounds, or inside a container element's client rectangle.
`initialValue`?	`Point`	Position before the first drag and during server rendering.
`pointerTypes`?	`readonly PointerKind[]`	Device kinds that may start a drag.
`exact`?	`boolean`	Only start when the pointer goes down on the handle itself, not a descendant.
`preventDefault`?	`boolean`	Call `preventDefault()` on pointer events while dragging.
`disabled`?	`MaybeRefOrGetter<boolean>`	Temporarily disable dragging.
`onStart`?	`(position: Point, event: PointerEvent) => boolean \| void`	Called before a drag starts. Return `false` to cancel it.
`onMove`?	`(position: Point, event: PointerEvent) => void`	Called after every position update.
`onEnd`?	`(position: Point, event: PointerEvent) => void`	Called when the drag ends.

`DraggableControls`

Reactive drag state returned by useDraggable.

Member	Type	Description
`x`	`Ref<number>`	Horizontal position (the element's left edge in client coordinates).
`y`	`Ref<number>`	Vertical position (the element's top edge in client coordinates).
`position`	`ComputedRef<Point>`	Current position snapshot.
`isDragging`	`Readonly<Ref<boolean>>`	Whether a drag is in progress.
`style`	`ComputedRef<string>`	`left`/`top` declaration for `position: fixed` or `absolute` placement.
`stop`	`() => void`	Remove listeners. Idempotent.