@ptahjs/dnd

@ptahjs/dnd

A lightweight, framework-agnostic drag-and-drop library built on the Pointer Events API. Designed with a plugin-first architecture for building canvas editors, sortable lists, and other interactive UIs.

Live Demo →

Features

• Pointer Events based — unified mouse, touch, and stylus support
• Plugin architecture — all behaviors (mirror, drop feedback, auto-scroll, transform) are optional plugins
• RAF-driven rendering — per-frame measure → compute → commit pipeline prevents layout thrashing
• Namespace support — isolate independent drag-and-drop zones within the same page
• Transform controller — drag-scope mode with built-in move, resize, and rotate for canvas editors
• Auto-scroll — edge-triggered scrolling during drag
• Zero dependencies — no runtime dependencies

Installation

npm install @ptahjs/dnd

Quick Start

import { Dnd, MirrorService, DropService } from '@ptahjs/dnd'
import '@ptahjs/dnd/style'

const dnd = new Dnd({ root: '#container' })
dnd.use(new MirrorService())
dnd.use(new DropService())

dnd.on('dragstart', (payload) => console.log('drag started', payload))
dnd.on('drop', (payload) => console.log('dropped', payload))
dnd.on('cancel', (payload) => console.log('cancelled', payload))

HTML Markup

Use data attributes to declare draggable elements and drop targets:

<!-- Root container -->
<div id="container">

  <!-- Drop target -->
  <div drop>
    <!-- Draggable element -->
    <div drag data-data='{"id":1,"type":"card"}'>Drag me</div>
  </div>

  <!-- Combined draggable + drop target -->
  <div dragdrop data-namespace="list-a">Item</div>

</div>

Attribute	Description
drag	Marks an element as draggable
drop	Marks an element as a drop target
dragdrop	Element is both draggable and a drop target
drag-handle	Restricts drag to a specific handle element inside the draggable
data-namespace	Groups draggable/drop elements — only elements in the same namespace interact
data-data	JSON data payload attached to the draggable
copy	Creates a copy on drop instead of moving
drag-scope	Defines a canvas-style scope for TransformControllerService
drop-indicator	Enables directional drop indicator (top, right, bottom, left, or all)
ignore-mirror	Dragging this element does not create a mirror clone
ignore-click	Clicks on this element do not affect active selection
resizable / rotatable	Per-element toggle for resize/rotate handles (defaults to true within drag-scope)
scale-ratio	Canvas zoom ratio applied to pointer coordinates in drag-scope mode

API

new Dnd(config?)

Creates a DnD instance.

Option	Type	Default	Description
root	HTMLElement | string	—	Root container element or CSS selector
threshold	number	3	Pixel distance before drag is considered started

Instance methods

// Register a plugin
dnd.use(plugin)

// Set or replace the root container
dnd.setRoot(element)

// Override drop permission (called every frame)
dnd.canDrop = (payload) => payload.data.type !== 'locked'

// Custom mirror rendering
dnd.renderMirror = (ctx) => {
  const el = document.createElement('div')
  el.textContent = 'Custom mirror'
  return el
}

// Event listeners
dnd.on('dragstart', handler)
dnd.on('drag', handler)
dnd.on('drop', handler)
dnd.on('cancel', handler)
dnd.off('drop', handler)

// Clean up everything
dnd.destroy()

dnd.monitor

The current drag session object. Read-only during an active drag.

Property	Description
active	Whether a drag session is active (pointer is down)
started	Whether the drag threshold has been exceeded
x, y	Current pointer coordinates
dx, dy	Delta from drag start
sourceEl	The element being dragged
handleEl	The handle element that was grabbed
currentDrop	The drop target currently under the pointer
currentAllowed	Whether canDrop returned true for the current target
currentDropRect	Bounding rect of the current drop target
indicatorRegion	Active drop indicator direction (top / right / bottom / left)
data	Parsed data from the draggable's data-data attribute
namespace	Namespace of the drag session
isCopy	Whether the draggable has the copy attribute

Events

All event handlers receive a payload object.

dnd.on('dragstart', ({ source, data, namespace }) => { /* ... */ })
dnd.on('drag',      ({ source, currentDrop, currentAllowed, x, y }) => { /* ... */ })
dnd.on('drop',      ({ source, currentDrop, indicatorRegion, data }) => { /* ... */ })
dnd.on('cancel',    ({ source, data }) => { /* ... */ })

Built-in Plugins (Services)

All services are optional. Register them with dnd.use(new ServiceName()).

MirrorService

Creates a floating clone of the dragged element that follows the pointer. Adds dnd-dragging class to the source element during drag.

dnd.use(new MirrorService())

The clone can be customized via dnd.renderMirror. To disable the mirror for a specific element, add the ignore-mirror attribute to it.

DropService

Maintains currentDrop, currentDropRect, and currentAllowed on the session. Applies dnd-canDrop or dnd-noDrop CSS class to the active drop target.

dnd.use(new DropService())

DropIndicatorService

Shows a directional insertion indicator (top/right/bottom/left) on the active drop target. Requires the drop target to have a drop-indicator attribute.

dnd.use(new DropIndicatorService())

<!-- Enable all four directions -->
<div drop drop-indicator>...</div>

<!-- Enable specific directions only -->
<div drop drop-indicator="top bottom">...</div>

The indicator element has class dnd-indicator and toggles dnd-indicator--top, dnd-indicator--right, dnd-indicator--bottom, dnd-indicator--left direction classes.

AutoScrollService

Automatically scrolls the nearest scrollable ancestor (or window) when the pointer approaches the edge of the container during drag.

dnd.use(new AutoScrollService({
  edge: 48,       // Edge trigger distance in px (default: 48)
  minSpeed: 180,  // Minimum scroll speed in px/s (default: 180)
  maxSpeed: 600,  // Maximum scroll speed in px/s (default: 600)
  allowWindowScroll: true  // Allow scrolling window (default: true)
}))

ActiveSelectionService

Tracks the selected (active) draggable per namespace. Adds dnd-active class to the selected element. Clicking outside clears the selection.

Within a drag-scope container, selecting an element injects resize/rotate handles into it.

dnd.use(new ActiveSelectionService())

TransformControllerService

Enables move, resize, and rotate within a drag-scope container. Designed for canvas editors with elements that use CSS transform for positioning.

dnd.use(new TransformControllerService({
  resizable: true,
  rotatable: true,
  boundary: true,         // Constrain movement within drag-scope
  scaleRatio: 1,          // Canvas zoom ratio (can also be set via data-scale-ratio)
  snapToGrid: false,
  gridX: 10,
  gridY: 10,
  aspectRatio: undefined, // Lock aspect ratio during resize
  minWidth: 10,
  minHeight: 10,
  maxWidth: 0,            // 0 = no limit
  maxHeight: 0,
  rotateSnap: false,
  rotateStep: 15,         // Snap angle in degrees
  snap: true,             // Snap-to-element alignment
  snapThreshold: 10,      // Snap threshold in px
  markline: true,         // Show alignment guide lines
}))

Emitted events (via dnd.on):

Event	Description
draggable:drag	Element moved — payload includes el, x, y, width, height, angle
draggable:resize	Element resized — same payload
draggable:rotate	Element rotated — same payload
draggable:drop	Drag ended with a committed transform — includes final x, y, width, height, angle

HTML markup for drag-scope:

<div drag-scope data-scale-ratio="1">
  <div drag resizable rotatable
       style="transform: translate(100px, 50px); width: 200px; height: 120px;">
    Canvas element
  </div>
</div>

CSS Classes

Class	Applied to	Description
dnd-dragging	Source element	While drag is active
dnd-mirror	Mirror clone	The floating drag ghost
dnd-active	Selected draggable	While element is selected
dnd-canDrop	Drop target	When canDrop returns true
dnd-noDrop	Drop target	When canDrop returns false
dnd-indicator	Indicator element	The drop direction indicator
dnd-indicator-active	Indicator element	When indicator is visible
dnd-indicator--top/right/bottom/left	Indicator element	Active direction

Writing a Custom Plugin

A plugin is a plain object or class instance with optional lifecycle hooks. Register it with dnd.use(plugin).

const myPlugin = {
  order: 50, // lower = earlier execution

  onAttach(dnd) {
    // Called once when plugin is registered
  },

  onRootChange(nextRoot, prevRoot, signal) {
    // Called when dnd.setRoot() is called
    nextRoot.addEventListener('contextmenu', handler, { signal })
  },

  onDown(ctx, event) {
    // Pointer down — drag not yet started
  },

  onStart(ctx) {
    // Drag threshold exceeded, drag is now active
  },

  onMeasure(ctx) {
    // Read-only DOM measurements (called every frame)
  },

  onCompute(ctx) {
    // Pure calculations based on measurements (no DOM writes)
  },

  onCommit(ctx) {
    // Write DOM changes via ctx.frame to batch updates
    ctx.frame.toggleClass(element, 'my-class', true)
    ctx.frame.setStyle(element, 'opacity', '0.5')
  },

  onAfterDrag(ctx) {
    // Post-commit hook, e.g. for auto-scroll
    // Return true or { scrolled: true } to request a re-render next frame
  },

  onEnd(ctx, meta) {
    // meta.ended: true = drop, false = cancel
    // meta.reason: 'pointerup' | 'blur' | 'destroy'
  },

  onDestroy(dnd, session) {
    // Cleanup when dnd.destroy() is called
  }
}

dnd.use(myPlugin)

Context object (ctx)

Property	Description
ctx.session	The current drag session (monitor)
ctx.store	Cross-session store (selectedByNs map)
ctx.frame	Frame command queue for batched DOM writes
ctx.adapter	DOM adapter for measurements and hit testing
ctx.dnd	The Dnd instance
ctx.payload(type)	Builds an event payload for the given event type

Architecture

Dnd (Facade)
├── PointerSensor      — captures pointerdown/move/up events
├── State              — finite state machine (DOWN → MOVE → END)
├── DomAdapter         — DOM queries and per-frame rect caching
├── RafScheduler       — requestAnimationFrame loop (only runs when dirty)
├── FrameContext       — batched DOM command queue for the current frame
└── PluginRuntime      — ordered plugin lifecycle dispatcher
    ├── MirrorService
    ├── DropService
    ├── DropIndicatorService
    ├── AutoScrollService
    ├── ActiveSelectionService
    └── TransformControllerService

Per-frame pipeline (while dragging):

pointermove → State.dispatch(MOVE) → scheduler.request()
                                           ↓
                                      requestAnimationFrame
                                           ↓
                               PluginRuntime.onMeasure   (read DOM)
                               PluginRuntime.onCompute   (pure math)
                               emit('drag', payload)
                               PluginRuntime.onCommit    (write DOM)
                               FrameContext.commit()
                               PluginRuntime.onAfterDrag (scroll, etc.)

License

MIT