/craft-garnish

Drag System — BaseDrag, Drag, DragSort, DragDrop, DragMove

Source

• src/web/assets/garnish/src/BaseDrag.js
• src/web/assets/garnish/src/Drag.js
• src/web/assets/garnish/src/DragSort.js
• src/web/assets/garnish/src/DragDrop.js
• src/web/assets/garnish/src/DragMove.js

Common Pitfalls

• Using DragSort without an axis constraint on a vertical list — set axis: Garnish.Y_AXIS to prevent horizontal jitter.
• Forgetting to call addItems() when new items are dynamically added — they won't be draggable.
• Not providing a handle selector — the entire item becomes the drag handle, blocking text selection and button clicks within.
• Using removeDraggee: true without an insertion element — there's no visual placeholder.
• Ignoring ignoreHandleSelector — by default, clicks on input, textarea, button, select, .btn within the handle don't initiate drag.

Table of Contents

• Class Hierarchy
• BaseDrag
• Drag
• DragSort
• DragDrop
• DragMove

Class Hierarchy

Garnish.Base
  └── BaseDrag       (mouse tracking, scroll handling, drag lifecycle)
        ├── Drag      (helper clones, visual feedback, draggee management)
        │     ├── DragSort   (reorder items in a list)
        │     └── DragDrop   (drag to drop targets)
        └── DragMove  (simple drag-to-reposition)

BaseDrag

Low-level drag infrastructure. Tracks mouse position, detects drag start (minimum distance threshold), manages scroll-while-dragging, and fires lifecycle events.

Constructor

var drag = new Garnish.BaseDrag($items, {
  handle: '.drag-handle',
  axis: Garnish.Y_AXIS,
  onDragStart: function () { },
  onDrag: function () { },
  onDragStop: function () { },
});

Settings (defaults)

Key Properties

Key Methods

Events

Scroll While Dragging

When the mouse nears the edge of the scroll container (within 25px), BaseDrag automatically scrolls in that direction using requestAnimationFrame. Works with both window and nested scrollable containers.

Drag

Extends BaseDrag. Creates "helper" clones of dragged elements that follow the cursor with a lag effect.

Constructor

var drag = new Garnish.Drag($items, {
  handle: '.drag-handle',
  axis: Garnish.Y_AXIS,
  removeDraggee: false,
  hideDraggee: true,
  helperOpacity: 1,
  helperBaseZindex: 1000,
  singleHelper: false,
  onDragStart: function () { },
  onDragStop: function () { },
});

Settings (defaults, in addition to BaseDrag)

Key Methods

Events (in addition to BaseDrag)

Helper System

When a drag starts, Drag clones each draggee element (adding .draghelper class), strips name attributes (to protect radio buttons), and positions them absolutely in <body>. Helpers follow the cursor with a configurable lag effect that creates a smooth, staggered animation for multi-element drags.

DragSort

Extends Drag. Enables reordering items within a container by dragging.

Constructor

var dragSort = new Garnish.DragSort($items, {
  handle: '.move.icon',
  axis: Garnish.Y_AXIS,
  container: this.$container,
  magnetStrength: 1,
  insertion: $('<div class="insertionmarker"/>'),
  onSortChange: function () { },
  onInsertionPointChange: function () { },
});

Settings (defaults, in addition to Drag)

Key Methods (in addition to Drag)

Events (in addition to Drag)

How It Works

1. dragStart: Records original indexes, creates insertion marker, pre-calculates item midpoints
2. drag: Finds closest item to cursor via midpoint distance, moves draggee in DOM
3. dragStop: Removes insertion, compares new indexes to old — fires sortChange if order changed

Performance: For large lists (200+ items), only viewport-visible items are checked during drag.

DragDrop

Extends Drag. Enables dragging items onto drop target areas.

Constructor

var dragDrop = new Garnish.DragDrop({
  dropTargets: $dropZones,           // jQuery collection or function returning elements
  activeDropTargetClass: 'active',
  onDropTargetChange: function ($activeDropTarget) {
    // $activeDropTarget is jQuery element or null
  },
});

// Add draggable items after construction
dragDrop.addItems($items);

Note: DragDrop's init() takes only settings (no items parameter). Add items via addItems() after construction.

Settings (in addition to Drag)

Key Properties

How It Works

1. onDragStart: Resolves drop targets (evaluates function if dropTargets is a function)
2. onDrag: Hit tests cursor against all drop targets each frame. When the active target changes, removes activeDropTargetClass from old, adds to new, calls onDropTargetChange
3. onDragStop: Removes activeDropTargetClass. Check this.$activeDropTarget to see where the item was dropped.

DragMove

Extends BaseDrag (not Drag). Simple drag-to-reposition — moves the element's CSS position to follow the cursor.

Constructor

var dragMove = new Garnish.DragMove(this.$element, {
  handle: '.drag-handle',
});

Used by Modal for draggable dialogs. No helpers, no clones — directly repositions the element.

How It Works

On each drag event, sets the target element's top and left CSS properties to match mouse offset.

See Also

• class-system.md — Garnish.Base (all drag classes extend this), addListener, destroy lifecycle
• utilities.md — Axis constants (Garnish.X_AXIS, Garnish.Y_AXIS), requestAnimationFrame, hitTest
• ui-widgets.md — Modal uses DragMove for draggable dialogs, Select often pairs with DragSort
• integration.md — How to set up drag interactions in Twig JS blocks and plugin asset bundles