hcg-draggable

A lightweight, zero-dependency JavaScript library that makes any element draggable. Built on the Pointer Events API so mouse, touch, and pen share one code path. Elements move with CSS transform: translate() for smooth, reflow-free dragging.

• GitHub: github.com/html-code-generator/hcg-draggable
• npm: npmjs.com/package/hcg-draggable
• Documentation & demo: html-code-generator.com/javascript/draggable-library

Features

• Zero dependencies, ~3 KB minified
• Drag handles, axis locking (x / y), grid snapping, containment
• Drag threshold, cancel regions, and click suppression after a real drag
• Bring to front on grab, revert on release
• Auto-init from data-hcg-draggable attributes
• onStart / onMove / onEnd callbacks and a full instance API

Demo

See the live documentation and interactive demo on the website:

https://www.html-code-generator.com/javascript/draggable-library

Open index.html in this repository for a local demo page.

Installation

Download

<link rel="stylesheet" href="hcg-draggable.css">
<script src="hcg-draggable.js"></script>

CDN

jsDelivr (npm):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hcg-draggable@1/hcg-draggable.css">
<script src="https://cdn.jsdelivr.net/npm/hcg-draggable@1/hcg-draggable.js"></script>

unpkg:

<link rel="stylesheet" href="https://unpkg.com/hcg-draggable@1/hcg-draggable.css">
<script src="https://unpkg.com/hcg-draggable@1/hcg-draggable.js"></script>

jsDelivr (GitHub):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/html-code-generator/hcg-draggable@1.0.0/hcg-draggable.css">
<script src="https://cdn.jsdelivr.net/gh/html-code-generator/hcg-draggable@1.0.0/hcg-draggable.js"></script>

Load CSS before JS. The global hcgDraggable function is available immediately after the script loads.

npm

npm install hcg-draggable

import hcgDraggable from "hcg-draggable";
import "hcg-draggable/hcg-draggable.css";

Usage

Basic

<div class="box" data-hcg-draggable>drag me</div>

Or in JavaScript:

var d = hcgDraggable(".box", {
  axis: null,
  handle: ".title-bar",
  cancel: "button, input",
  dragThreshold: 5,
  containment: "parent",
  grid: [20, 20],
  revert: false,
  onEnd: function (e) { console.log(e.x, e.y, e.moved); }
});

hcgDraggable(target, options) accepts a CSS selector, an element, or a NodeList. It returns a single instance, or an array when the target matches multiple elements.

Data attributes

Attribute	Maps to
data-hcg-draggable	enables auto-init
data-hcg-handle	handle
data-hcg-cancel	cancel
data-hcg-threshold	dragThreshold
data-hcg-axis	axis - x or y
data-hcg-containment	containment - parent, viewport, selector, etc.
data-hcg-grid	grid - 20 or 20,40
data-hcg-disabled	disabled
data-hcg-bring-to-front	bringToFront
data-hcg-revert	revert

Instance methods

d.enable();
d.disable();
d.setOption("axis", "x");
d.getPosition();   // -> { x, y }
d.setPosition(120, 40);
d.contain();       // re-clamp inside containment
d.reset();
d.destroy();

Statics: hcgDraggable.init(root), hcgDraggable.destroyAll().

Documentation

Full API reference, live demos, React examples, options tables, and copy-paste snippets:

https://www.html-code-generator.com/javascript/draggable-library

License

MIT - see LICENSE.