Sortable List

A drag-and-drop sortable list component built with dnd-kit.

  • Item 1

    Description for item 1

  • Item 2

    Description for item 2

  • Item 3

    Description for item 3

  • Item 4

    Description for item 4

Installation

Usage

import {
  SortableList,
  SortableItem,
  SortableDragHandle,
} from "@/components/ui/sortable-list";
"use client";
 
import { useState } from "react";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemTitle,
} from "@/components/ui/item";
import {
  SortableList,
  SortableItem,
  SortableDragHandle,
} from "@/components/ui/sortable-list";
 
const initialItems = [
  {
    id: "1",
    title: "Item 1",
    description: "Description for item 1",
  },
  {
    id: "2",
    title: "Item 2",
    description: "Description for item 2",
  },
  {
    id: "3",
    title: "Item 3",
    description: "Description for item 3",
  },
];
 
export function SortableListDemo() {
  const [items, setItems] = useState(initialItems);
 
  return (
    <SortableList
      className="w-full gap-1"
      items={items}
      onChange={setItems}
      renderItem={(item) => (
        <SortableItem id={item.id}>
          <Item className="w-full border-border" size="sm" variant="muted">
            <ItemActions>
              <SortableDragHandle />
            </ItemActions>
            <ItemContent>
              <ItemTitle>{item.title}</ItemTitle>
              <ItemDescription>{item.description}</ItemDescription>
            </ItemContent>
          </Item>
        </SortableItem>
      )}
    />
  );
}

API Reference

SortableList

The main container component for sortable items. Built with @dnd-kit for accessibility and smooth drag-and-drop interactions.

Props

PropTypeDescription
itemsTItem[]Array of items to display. Each item must have an id property.
onChange(items: TItem[]) => voidCallback fired when items are reordered.
renderItem(item: TItem, index: number, isOverlay?: boolean) => React.ReactNodeFunction to render each item. The isOverlay parameter indicates when an item is being dragged.
classNamestringAdditional CSS classes for the list container.

SortableItem

A wrapper component for individual sortable items.

Props

PropTypeDescription
idstring | numberUnique identifier for the item (must match item.id).
classNamestringAdditional CSS classes.
childrenReact.ReactNodeContent of the sortable item.

SortableDragHandle

A pre-built drag handle button that uses the sortable context. Extends shadcn/ui's Button component.

Props

Inherits all props from Button component.

Notes

Important Information:
  • Custom Component: This component is not part of the default shadcn/ui registry. It is custom to this project for drag-and-drop audio queue reordering.
  • Built with dnd-kit: This component is built on top of @dnd-kit, which includes keyboard-friendly drag-and-drop behavior. See the

    dnd-kit documentation

    for details.
  • Drag Handle: SortableDragHandle uses the project Button primitive and ships pre-wired accessibility attributes.
  • Item IDs: Each item must have a unique id property. The id type must match between the item object and the SortableItem component.
  • Usage in Audio Components: This component is used by AudioTrackList for queue reordering.

Last updated 4/15/2026