Guide · Open source

How to use Sortable: drag-and-drop lists in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Sortable is a JavaScript library that lets people reorder list items by dragging them, either within one list or between lists. It works on touch devices and modern browsers and does not need jQuery or a specific UI framework. This guide shows you how to install it, create a sortable list, and configure common options so you can add reorderable lists without writing your own drag logic.

SortableSortableJS/Sortable · ★ 31.2k · MIT Install options & downloads

Quick start

1Install the package. Run npm install sortablejs --save in your project folder.
2Import Sortable. Add import Sortable from 'sortablejs'; to the file where you build your list.
3Mark up a list. Create a ul or other element with li or other child items and give it an id.
4Create the sortable. Get the element with document.getElementById and pass it to Sortable.create().
5Set options. Pass an options object to new Sortable(), for example to set a handle or animation speed.
6Handle the drop. Use an onEnd callback and read evt.oldIndex and evt.newIndex to save the new order.

What Sortable is and who it is for

Sortable is a code library, not a finished app. You add it to a web project, and it makes the list elements on your page draggable and reorderable.

The README points to web developers adding reorderable lists to a site or app, and to teams using React, Vue, Angular or similar frameworks who want a framework-specific wrapper. It is less suited to non-developers looking for a ready-made tool, or to drag-and-drop for layouts that are not lists.

Good fit: adding reorderable lists to a site or app
Good fit: projects that need drag handles, multi-drag or moving items between lists
Not a fit: people who want a finished app with no coding

Install Sortable with npm or Bower

The README lists two install methods. Run the npm command inside your project folder to add the sortablejs package. The README also gives a Bower command if your project uses Bower.

The README does not list any prerequisites for installing Sortable.

npm install sortablejs --save

bower install --save sortablejs

Import Sortable into your project

Import the default build for most projects. The README also lists a core build without default plugins and a complete build with all plugins, for cases where you want to control which plugins load.

To add specific plugins, such as MultiDrag or Swap, import them and register them with Sortable.mount().

Default: import Sortable from 'sortablejs'
Core only: sortablejs/modular/sortable.core.esm.js
Complete (all plugins): sortablejs/modular/sortable.complete.esm.js

import Sortable from 'sortablejs';

import Sortable, { MultiDrag, Swap } from 'sortablejs';
Sortable.mount(new MultiDrag(), new Swap());

Create your first sortable list

Give your list an id in your HTML, then pass the element to Sortable.create(). The README's example uses a ul with li items, and it notes that you can use any element for the list and its items, such as div elements.

Once created, the list items can be dragged to reorder them.

<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);

Configure options

Sortable uses an options object passed as the second argument to new Sortable(). The README lists many options. The ones most people reach for first are below.

handle sets a drag handle selector inside each item, so only that part starts a drag. filter sets selectors that should not start a drag. animation sets the move animation in milliseconds, where 0 turns it off. group lets lists share items with each other, which is how you move items between lists.

Event callbacks such as onEnd tell you when a drop happens. Use evt.oldIndex and evt.newIndex to find where an item moved from and to, and evt.from and evt.to to see which lists were involved.

handle: drag handle selector, for example ".my-handle"
filter: selectors that do not lead to dragging
animation: ms for move animation, 0 for none
group: a name shared by lists that exchange items
onEnd, onAdd, onUpdate, onRemove: callbacks for drops and changes
disabled: set to true to turn the sortable off

var sortable = new Sortable(el, {
	group: "name",
	animation: 150,
	handle: ".my-handle",
	onEnd: function (evt) {
		console.log(evt.oldIndex, evt.newIndex);
	}
});

Use advanced features: multi-drag and touch

Sortable supports touch devices. The README lists a delayOnTouchOnly option that delays dragging only on touch, and touchStartThreshold, which sets how many pixels a touch can move before a delayed drag is cancelled.

Multi-drag is available as a plugin in the README. It lets users drag more than one item at a time. The README links to a dedicated MultiDrag plugin folder for details.

Touch: delay and delayOnTouchOnly options
Multi-drag: MultiDrag plugin, imported and mounted as shown above
Between lists: use the same group value on each list

What people use it for

Reordering a list of tasks or to-dos on a web page
Letting users move items between two lists, such as available and selected options
Adding drag handles so users can select text in items without starting a drag
Building a framework-based list with a wrapper for React, Vue or Angular

Frequently asked questions

Is Sortable free to use?

Yes. The README lists the licence as MIT. Check the LICENSE file in the repository for the full terms before you ship it in a product.

How do I install Sortable?

Use npm install sortablejs --save for npm, or bower install --save sortablejs for Bower. Then import Sortable from 'sortablejs' in your project.

Does Sortable need jQuery?

No. The README says no jQuery is required. A separate jQuery support package exists if you want it.

Does Sortable work on touch devices?

Yes. The README says it supports touch devices, and it provides delay options for touch use.

Which browsers does Sortable support?

The README says it supports modern browsers and mentions IE9. Test against your own browser needs, since the README does not give a full support matrix.

Can I use Sortable with React or Vue?

The README lists framework wrappers for Angular, React, Vue, Knockout, Polymer, Ember and Meteor. Each one is a separate project linked from the README.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Sortable suits developers who want reorderable lists with a simple options-based API and no jQuery or framework dependency. It is a code library, so non-developers wanting a finished app should look elsewhere. Teams needing drag-and-drop for layouts beyond lists should check the docs before committing.

Install options & downloads