Dragee

A lightweight, dependency-free JavaScript library for drag and drop, sortable lists, and target-based interactions.

Full Documentation

Installation

npm install dragee

Core Components

Draggable

The base class for making elements draggable.

import { Draggable, Point } from 'dragee';

const element = document.getElementById('draggable');
const calculusFx = (x) => {
  x = x / 100;
  return (x * Math.sin(x * x) + 1) * 10 + 80;
};

const draggable = new Draggable(element, {
  bound: (point, size) => {
    const retPoint = point.clone();
    retPoint.y = calculusFx(point.x);
    return retPoint;
  },
  position: new Point(210, calculusFx(210))
});

// Events
draggable.on('drag:start', () => console.log('Started dragging'));
draggable.on('drag:move', () => console.log('Dragging'));
draggable.on('drag:end', () => console.log('Finished dragging'));

Common options

| Option | Type | Default | Description | | --- | --- | --- | --- | | container | Element | element.offsetParent | Coordinate space for position calculations | | position | Point | current offset | Initial position | | bound / bounding | (point, size) => Point | Bound | identity | Movement constraint | | handler | Element | string | element | Sub-element (or selector) that starts the drag | | dragStartThreshold | number | 0 | Pixels the pointer must travel before drag activates. Prevents accidental drags when the user just wants to click | | shouldRemoveZeroTranslate | boolean | false | Remove translate3d(0,0,0) from the inline transform when resting | | nativeDragAndDrop | boolean | false | Use HTML5 drag-and-drop events instead of mouse/touch | | emulateNativeDragAndDropOnTouch | boolean | false | On touch devices, emulate native drag-and-drop | | stopPropagationOnDragStart | boolean | false | Stop event propagation on drag start |

Predefined Bounding Functions

Dragee provides several predefined bounding functions to constrain draggable movement:

// Bound to element's boundaries
BoundToElement.bounding(element, container)

// Bound to specific rectangle
BoundToRectangle.bounding(rectangle)

// Bound to vertical line with Y-axis constraints
BoundToLineX.bounding(x, startY, endY)

// Bound to horizontal line with X-axis constraints
BoundToLineY.bounding(y, startX, endX)

// Bound to line between two points
BoundToLine.bounding(startPoint, endPoint)

// Bound to circle
BoundToCircle.bounding(center, radius)

// Bound to arc
BoundToArc.bounding(center, radius, startAngle, endAngle)

Sortable

Two types of sortable lists are available:

List

Basic sortable list implementation.

import { Draggable, List } from 'dragee';

const gridContainer = document.querySelector('.grid-container');
const gridItems = gridContainer.querySelectorAll('.grid-item');

const gridDraggables = Array.from(gridItems).map(item =>
  new Draggable(item, {
    container: gridContainer,
    nativeDragAndDrop: true
  })
);

new List(gridDraggables)

BubblingList

Vertical sortable list that uses bubbling algorithm for smooth and natural sorting behavior.

import { Draggable, BubblingList } from 'dragee';

const listContainer = document.querySelector('.sortable-demo-list');
const listItems = listContainer.querySelectorAll('.items');

const draggableItems = Array.from(listItems).map((item) =>
  new Draggable(item, {
    container: listContainer,
    nativeDragAndDrop: true,
    emulateNativeDragAndDropOnTouch: true
  })
);

new BubblingList(draggableItems);

Targets

Target areas for draggable elements.

import { Target, FloatLeftStrategy, transformedSpaceDistanceFactory } from 'dragee';

const target = new Target(element, draggables, {
  timeEnd: 200,
  timeExcange: 400,
  container: parentElement,
  strategy: new FloatLeftStrategy(
    () => target.getRectangle(),
    {
      radius: 80,
      getDistance: transformedSpaceDistanceFactory({ x: 1, y: 4 }),
      removable: true
    }
  )
});

Target Strategies

FloatLeftStrategy

Orders draggables from top to bottom, positioning them on the left side of the target area.

new Target(element, draggables, {
  strategy: new FloatLeftStrategy(
    () => target.getRectangle(),
    {
      radius: 80,
      getDistance: transformedSpaceDistanceFactory({ x: 1, y: 4 })
    }
  )
});

FloatRightStrategy

Orders draggables from top to bottom, positioning them on the right side of the target area.

new Target(element, draggables, {
  strategy: new FloatRightStrategy(
    () => target.getRectangle(),
    {
      radius: 80,
      getDistance: transformedSpaceDistanceFactory({ x: 1, y: 4 })
    }
  )
});

NotCrossingStrategy

A free-form positioning strategy that prevents draggables from overlapping. Items can be placed anywhere within the target area but will maintain their own space without intersecting with other items.

new Target(element, draggables, {
  strategy: new NotCrossingStrategy(
    () => target.getRectangle()
  )
});