Quick Start

comins-sortable@0.1.6

Playground paths below are local routes for the module repository’s development server. They are not live routes on this documentation site.

These guides explain the public APIs of Comins Sortable. Use the repository Playground below to try its sortable interactions.

Install the package and the peer dependency required by your adapter.

# Vanilla JavaScript
npm install comins-sortable@0.1.6

# React
npm install comins-sortable@0.1.6 react@19.3.0 react-dom@19.3.0

# Vue
npm install comins-sortable@0.1.6 vue@3.5.42

# Svelte
npm install comins-sortable@0.1.6 svelte@5.57.0

Import from the adapter-specific public export. Import the stylesheet when you use the built-in placeholder preset.

import { SortableArea, SortableRoot } from 'comins-sortable/react';
import 'comins-sortable/styles.css';

Framework adapters are controlled. Your application owns each items array, and onItemsChange (or Vue’s update:modelValue) must render the proposed array. Comins Sortable verifies that render on the next frame. A missing or structurally stale render rolls back with state-not-committed.

In 0.1.4, a drop is also rejected with state-not-committed if the source or destination item order, IDs, or item elements differ from drag activation. No change is emitted for that drop. External source updates are preserved when the drag is cancelled; removed items are not reinserted. Failed transfers retain the existing multi-selection and range anchor.

Every item needs a stable, group-wide ID. Do not derive itemKey from an array index.

Run the repository Playground:

git clone https://github.com/kim1124/comins-sortable.git
cd comins-sortable
git checkout ff13440ff099a2c5f7f4c6cc2d72f4977db1c942
npm ci --ignore-scripts
npm run dev

Open /examples/simple/react, then use View code to inspect the selected adapter.

Playground cards use a left drag handle by default. Drag the handle to reorder and select body text to copy it. Drag start areas also compares title-only and whole-card activation. This is a demo choice: library consumers opt into handles with handle. See Handle and Acceptance for the modes and the current Safari title-drag limitation.

Continue with Core Concepts or select an adapter from the documentation index.

Runnable example · Source guide for this version