SortableJS Deployment and Usage Guide

Prerequisites

• Runtime: Modern web browser (supports HTML5 Drag and Drop API)
• Tools: Node.js and npm (for package management)
• Optional: Package managers like Bower or Yarn

Installation

Using npm

npm install sortablejs --save

Using Bower

bower install --save sortablejs

Manual Download

Download from the official repository or use CDN links.

Configuration

Import Options

Default SortableJS

import Sortable from 'sortablejs';

Core SortableJS (without default plugins)

import Sortable from 'sortablejs/modular/sortable.core.esm.js';

Complete SortableJS (with all plugins)

import Sortable from 'sortablejs/modular/sortable.complete.esm.js';

Cherrypick Plugins

import Sortable, { MultiDrag, Swap } from 'sortablejs';

Sortable.mount(new MultiDrag(), new Swap());

Available Options

var sortable = new Sortable(el, {
  group: "name",  // or { name: "...", pull: [true, false, 'clone', array], put: [true, false, array] }
  sort: true,  // sorting inside list
  delay: 0, // time in milliseconds to define when the sorting should start
  disabled: false, // Disables the sortable if set to true.
  animation: 150,  // ms, animation speed moving items when sorting
  handle: ".my-handle",  // Drag handle selector within list items
  filter: ".ignore-elements",  // Selectors that do not lead to dragging
  draggable: ".item",  // Specifies which items inside the element should be draggable
  ghostClass: "sortable-ghost",  // Class name for the drop placeholder
  chosenClass: "sortable-chosen",  // Class name for the chosen item
  dragClass: "sortable-drag",  // Class name for the dragging item
  swapThreshold: 1, // Threshold of the swap zone
  direction: 'horizontal', // Direction of Sortable
  forceFallback: false,  // ignore the HTML5 DnD behaviour and force the fallback
  fallbackClass: "sortable-fallback"  // Class name for the cloned DOM Element when using forceFallback
});

Build & Run

Basic Usage

<ul id="items">
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
</ul>

var el = document.getElementById('items');
var sortable = Sortable.create(el);

Development

1. Include SortableJS in your project via npm or CDN
2. Initialize Sortable on your target element
3. Customize options as needed

Production

• Use the minified version: Sortable.min.js
• Consider tree-shaking for smaller bundle size
• Use appropriate plugins based on your requirements

Deployment

Static Hosting

Since SortableJS is a client-side JavaScript library, you can deploy it on any static hosting platform:

• Vercel (formerly ZEIT Now)
• Netlify
• GitHub Pages
• Surge.sh
• AWS S3 with static website hosting

Framework Integration

SortableJS integrates with various frameworks:

React

npm install react-sortablejs

Angular

npm install angular-sortablejs

Vue

npm install vue-draggable

Ember

npm install ember-sortablejs

Troubleshooting

Common Issues

1. Drag and Drop not working in older browsers

• Ensure you're using a modern browser that supports HTML5 Drag and Drop API
• For IE9 support, use the fallback mode: forceFallback: true

2. Items not draggable

• Check that the draggable option is correctly set
• Ensure the filter option isn't excluding your items
• Verify that the handle selector is correct if using drag handles

3. Animation issues

• Adjust the animation option (in milliseconds)
• Check CSS transitions on the ghostClass, chosenClass, and dragClass

4. Multi-list drag issues

• Configure the group option correctly for cross-list dragging
• Ensure pull and put settings are properly configured

5. Touch device issues

• Set delayOnTouchOnly: true for better touch experience
• Adjust touchStartThreshold for touch sensitivity

Performance Tips

1. Use virtualization for large lists to improve performance
2. Lazy load SortableJS if not needed immediately
3. Optimize CSS by minimizing complex animations
4. Use appropriate plugins only when needed

Browser Compatibility

SortableJS supports modern browsers including IE9+. For detailed compatibility, check the Can I Use page for HTML5 Drag and Drop API.

Plugin Issues

If using plugins like MultiDrag or Swap:

• Ensure plugins are properly mounted: Sortable.mount(new MultiDrag())
• Check plugin-specific options and requirements
• Verify plugin compatibility with your SortableJS version

Event Handling

For custom event handling:

var sortable = Sortable.create(el, {
  onEnd: function (evt) {
    var itemEl = evt.item;  // dragged HTMLElement
    evt.to;    // target list
    evt.from;  // previous list
    evt.oldIndex;  // element's old index within old parent
    evt.newIndex;  // element's new index within new parent
  }
});