Overview
Libs
Resources
- 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
| Prop | Type | Description |
|---|---|---|
items | TItem[] | Array of items to display. Each item must have an id property. |
onChange | (items: TItem[]) => void | Callback fired when items are reordered. |
renderItem | (item: TItem, index: number, isOverlay?: boolean) => React.ReactNode | Function to render each item. The isOverlay parameter indicates when an item is being dragged. |
className | string | Additional CSS classes for the list container. |
SortableItem
A wrapper component for individual sortable items.
Props
| Prop | Type | Description |
|---|---|---|
id | string | number | Unique identifier for the item (must match item.id). |
className | string | Additional CSS classes. |
children | React.ReactNode | Content 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
SortableDragHandlecomponent uses shadcn/ui'sButtoncomponent and provides a pre-configured drag handle with proper accessibility attributes. - Item IDs: Each item must have a unique
idproperty. Theidtype must match between the item object and theSortableItemcomponent.
Last updated 11/19/2025