drag-kit: A Lightweight Drag‑and‑Drop Library for Vue, React and Plain JavaScript

In modern front‑end development, drag‑and‑drop functionality is a core UI interaction, especially when complex scenarios such as high‑performance dragging, cross‑iframe operations, or responsive layouts are required. This guide introduces drag-kit, a lightweight yet feature‑rich drag‑and‑drop library that works seamlessly with popular frameworks like Vue and React.

Why Choose drag-kit ?

The library addresses common limitations of other drag‑and‑drop solutions by offering high performance, cross‑iframe support, responsive behavior, rich features (direction lock, grid alignment, area restriction, auto‑snap), and compatibility with Vue 2, Vue 3 and React on both PC and mobile devices.

Quick Start: Basic Drag

Install the package: npm install drag-kit The current stable version is [email protected], which includes performance improvements for multiple scenarios.

Basic draggable example:

import { createDraggable } from 'drag-kit';

createDraggable('draggableElementId', {
  initialPosition: { x: '100px', y: '100px' }, // optional, supports calc
});

Core Capabilities

Drag Modes

drag-kit

supports three drag modes:

screen mode : Drag within the visible viewport, ideal for dialogs or toolbars.

page mode : Drag anywhere on the page, ignoring viewport limits, suitable for pages with scrollbars.

container mode : Drag inside a specified container via the dragArea option.

Key Features

Direction lock ( lockAxis ) : Restrict movement to the X axis, Y axis, or none.

Edge buffer ( edgeBuffer ) : Define a safety margin around the drag area.

Grid alignment ( gridSize ) : Snap movement to a configurable grid.

Auto‑snap mode ( snapMode ) : Automatically snap to viewport edges.

Position persistence ( shouldSave ) : Save the final position to local storage.

Cross‑iframe Drag

Cross‑iframe dragging often involves boundary calculations, event propagation, and security concerns. drag-kit handles these complexities, providing precise position calculation and smooth interaction across iframe boundaries.

Mobile Device Support

The library works on touch devices by allowing calc and percentage values for responsive positioning:

createDraggable('draggableElementId', {
  mode: 'screen',
  initialPosition: { x: 'calc(100vw - 120px)', y: '10%' }
});

Performance Optimization

To avoid unnecessary overhead, destroy the draggable instance when it is no longer needed. Example for a Vue 3 component:

<template>
  <div id="draggableElement" style="display: none;">Drag me!</div>
</template>

<script lang="ts">
import { onMounted, onBeforeUnmount } from 'vue';
import { createDraggable } from 'drag-kit';

export default {
  setup() {
    let draggable;
    onMounted(() => {
      draggable = createDraggable('draggableElement', {
        initialPosition: { x: '100px', y: '200px' }
      });
    });
    onBeforeUnmount(() => {
      draggable?.destroy();
    });
  }
};
</script>

Advanced Feature Extensions

Beyond the basics, drag-kit offers direction lock, drag‑area constraints, responsive layout handling, and auto‑snap. These can be combined to meet complex UI requirements.

Visible‑area Drag

createDraggable('draggableElementId', {
  initialPosition: { x: '100px', y: '100px' }
});

Page‑range Drag

createDraggable('draggableElementId', { mode: 'page' });

Container‑bounded Drag

createDraggable('draggableElementId', {
  mode: 'container',
  dragArea: document.getElementById('dragContainer'),
  edgeBuffer: 20
});

Direction‑locked Drag

createDraggable('draggableElementId', { lockAxis: 'x' });

Grid Alignment

createDraggable('draggableElementId', { gridSize: 50 });

Auto‑snap Mode

createDraggable('draggableElementId', { snapMode: 'auto' });

Cross‑Framework Integration

Vue Integration

Works with both Vue 2 and Vue 3. Example:

<template>
  <div id="draggableElement" style="display: none;">Drag me!</div>
</template>

<script lang="ts">
import { onMounted, onBeforeUnmount } from 'vue';
import { createDraggable } from 'drag-kit';

export default {
  setup() {
    let draggable;
    onMounted(() => {
      draggable = createDraggable('draggableElement', {
        initialPosition: { x: '100px', y: '200px' }
      });
    });
    onBeforeUnmount(() => {
      draggable?.destroy();
    });
  }
};
</script>

React Integration

Example using hooks:

import React, { useEffect } from 'react';
import { createDraggable } from 'drag-kit';

const DraggableComponent: React.FC = () => {
  useEffect(() => {
    const draggable = createDraggable('draggableElement', {
      initialPosition: { x: '100px', y: '200px' }
    });
    return () => {
      draggable?.destroy();
    };
  }, []);

  return (
    <div id="draggableElement" style={{ display: 'none' }}>Drag me!</div>
  );
};

export default DraggableComponent;

Pure JavaScript Usage

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Drag Kit Example</title>
  <style>
    #draggableElement {
      width: 100px;
      height: 100px;
      background-color: #3498db;
      position: absolute;
      cursor: move;
    }
  </style>
</head>
<body>
  <div id="draggableElement">Drag me!</div>
  <script src="https://unpkg.com/drag-kit/lib/drag-kit.umd.js"></script>
  <script>
    document.addEventListener('DOMContentLoaded', () => {
      const draggable = dragKit.createDraggable('draggableElement', {
        initialPosition: { x: '50px', y: '50px' }
      });
    });
  </script>
</body>
</html>

Conclusion

drag-kit

is a lightweight yet powerful drag‑and‑drop library capable of handling complex requirements such as cross‑iframe dragging, direction locking, boundary restriction, and grid alignment. Its cross‑framework compatibility with Vue 2, Vue 3, and React makes it a versatile solution for both simple projects and enterprise‑level applications.