- 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:
- Custom Component: This component is not part of the default shadcn/ui registry. It's a custom component built specifically for audio/ui to enable drag-and-drop reordering of tracks in the queue.
- 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 thednd-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. - Usage in Audio Components: This component is used by
AudioTrackListto enable drag-and-drop reordering of tracks in the queue.
- Drag Handle: The
Last updated 12/4/2025