useDraggable

Makes any element draggable using Pointer Events. Returns Observable values for position (x$, y$), drag state (isDragging$), and a ready-to-use CSS style string (style$).

Demo

Draggable

No active drag

Basic

X only

Y only

Toggle

Disable rose box

Usage

Basic drag

Hook

import { useRef$ } from "@usels/core";
import { useDraggable } from "@usels/web";

function DraggableBox() {
  const el$ = useRef$<HTMLDivElement>();
  const { x$, y$ } = useDraggable(el$);

  return (
    <div ref={el$} style={{ position: "fixed", left: `${x$.get()}px`, top: `${y$.get()}px` }}>
      Drag me
    </div>
  );
}

Scope

import { createRef$ } from "@usels/core";
import { createDraggable } from "@usels/web";

function DraggableBox() {
  "use scope";
  const el$ = createRef$<HTMLDivElement>();
  const { x$, y$ } = createDraggable(el$);

  return (
    <div ref={el$} style={{ position: "fixed", left: `${x$.get()}px`, top: `${y$.get()}px` }}>
      Drag me
    </div>
  );
}

Axis restriction

Restrict movement to a single axis.

const { x$ } = useDraggable(el$, { axis: "x" }); // horizontal only
const { y$ } = useDraggable(el$, { axis: "y" }); // vertical only

With handle

Attach drag to a specific handle element instead of the whole target.

// @noErrors
import { useRef$ } from "@usels/core";
import { useDraggable } from "@usels/web";

function WithHandle() {
  const el$ = useRef$<HTMLDivElement>();
  const handle$ = useRef$<HTMLDivElement>();
  const { style$ } = useDraggable(el$, { handle: handle$ });
  // ...
}

Container boundary

Clamp drag position inside a container element.

const { style$ } = useDraggable(el$, {
  containerElement: container$,
});

Restrict to viewport

const { style$ } = useDraggable(el$, {
  restrictInView: true,
});

Callbacks

const { isDragging$ } = useDraggable(el$, {
  onStart: (pos, e) => {
    if (someCondition) return false; // cancel drag
  },
  onMove: (pos, e) => console.log(pos),
  onEnd: (pos, e) => savePosition(pos),
});

Reactive position update

x$ and y$ are writable Observables — setting them directly updates style$ and position$.

const { x$, y$, style$, position$ } = useDraggable(el$);
x$.set(100);
y$.set(200);
// style$.get() === 'left: 100px; top: 200px;'

Type

Parameters

Parameter	Type	Description
target	MaybeEventTarget	- Element to make draggable (Ref$, Observable<Element|null>, raw Element, etc.).
options	UseDraggableOptions (optional)	- Configuration (supports DeepMaybeObservable — each field may be an Observable).

UseDraggableOptions

Option	Type	Default	Description
exact	boolean	-	Only start drag if pointerdown target exactly matches the element. Default: false
preventDefault	boolean	-	Call preventDefault on pointer events. Default: false
stopPropagation	boolean	-	Call stopPropagation on pointer events. Default: false
capture	boolean	-	Use capture phase for pointerdown. Default: false
handle	MaybeEventTarget	-	Restrict drag to a specific handle element
containerElement	MaybeEventTarget	-	Clamp drag position inside this container element
initialValue	Position	-	Initial position. Read once at mount time. Default: { x: 0, y: 0 }
onStart	((position: Position, event: PointerEvent) => false | void)	-	Called on drag start. Return false to cancel.
onMove	((position: Position, event: PointerEvent) => void)	-	Called on each drag move
onEnd	((position: Position, event: PointerEvent) => void)	-	Called on drag end
axis	"x" | "y" | "both"	-	Restrict movement axis. Default: ‘both’
disabled	boolean	-	Disable dragging
pointerTypes	("mouse" | "pen" | "touch")[]	-	Filter by pointer type. Default: all types allowed
restrictInView	boolean	-	Clamp drag position inside the viewport. Default: false
window	WindowSource	-	-

Returns

UseDraggableReturn

Name	Type	Description
x$	ObservablePrimitive<number>	Current X position
y$	ObservablePrimitive<number>	Current Y position
position$	Observable<Position>	Current position as { x, y }
isDragging$	ObservableBoolean<boolean>	Whether currently dragging
style$	ObservablePrimitive<string>	CSS position string: “left: Xpx; top: Ypx;“

Source

View on GitHub