Sortable List

PreviousNext

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

pnpm dlx shadcn@latest add @audio/sortable-list

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:
  • Built with dnd-kit: This component is built on top of @dnd-kit, which provides full keyboard navigation support. Users can reorder items using arrow keys and keyboard shortcuts. See the dnd-kit documentation for more details.
  • Drag Handle: The SortableDragHandle component uses shadcn/ui's Button component and provides a pre-configured drag handle with proper 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.

Last updated 11/19/2025