drag-tabs

3.0.0 verified Fri May 01 auth: no javascript

A tiny utility for making tabs inside a container draggable. It emits drag, start, cancel, and end events but does not perform the actual dragging—leaving that to the consumer. The library is minimal and singleton per element. Current version is 3.0.0, released as ESM-only (breaking from v2.x). The project is maintained by bpmn-io and follows an irregular release cadence. Key differentiators: lightweight, no DOM manipulation beyond eventing, focuses solely on drag detection, and works with any tab-based layout. Alternatives like SortableJS provide full drag-and-drop out of the box.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM import in a CommonJS environment (e.g., Node without "type": "module").

fix

Set "type": "module" in your package.json, or use .mjs extension for your file.

error TypeError: dragTabs is not a function ↓

cause Using import { dragTabs } ... but the export is default, not named.

fix

Use import dragTabs from 'drag-tabs' (without curly braces).

Warnings

breaking v3.0.0 turned the module into ESM-only. CommonJS require() will break. ↓

fix Use import dragTabs from 'drag-tabs' instead of require().

breaking v3.0.0 updated min-dom to 5.2.0 and min-dash to 5.0.0, which may introduce breaking changes in those dependencies. ↓

fix Ensure your project uses compatible versions of min-dom and min-dash (>=5.0.0).

deprecated v1.0.0 declared ES modules; earlier versions used CommonJS. No further support for CJS builds. ↓

fix Migrate to ES module imports. Use an ESM-aware bundler.

gotcha The library does not perform actual DOM manipulation of tab order; it only fires events. You must handle moving tabs yourself. ↓

fix Listen to the 'drag' event and rearrange the tab elements in the DOM based on context.newIndex.

gotcha DragTabs is a singleton per element. Re-initializing on the same element will overwrite the previous instance. ↓

fix Call dragger.update() instead of creating a new instance if the tabs change.

Install

npm install drag-tabs

yarn add drag-tabs

pnpm add drag-tabs

Imports

default

wrong

const dragTabs = require('drag-tabs')

correct

import dragTabs from 'drag-tabs'

v3 is ESM-only; CJS require() fails. Use import.

DragTabs

wrong

import { DragTabs } from 'drag-tabs';

correct

import dragTabs from 'drag-tabs';
const dragger = dragTabs(element, options);

Default export is a function; there is no named export DragTabs.

EventEmitter

wrong

import { EventEmitter } from 'drag-tabs';

correct

import dragTabs from 'drag-tabs';
const dragger = dragTabs(element, options);
dragger.on('drag', handler);

EventEmitter interface is on the returned dragger instance, not exported.

Quickstart

Creates a draggable tabs instance, listens to drag and cancel events, and logs the drag context.

import dragTabs from 'drag-tabs';

const container = document.querySelector('.tab-container');
const dragger = dragTabs(container, {
  selectors: {
    tabsContainer: '.tabs',
    tab: '.tab',
    ignore: '.ignore'
  }
});

dragger.on('drag', (context) => {
  console.log('Dragging tab', context.dragTab, 'to index', context.newIndex);
  // move the tab in DOM based on context.newIndex
});

dragger.on('cancel', (context) => {
  console.log('Drag cancelled, reset tab to original position');
});