Sortable

Installation

pnpm dlx shadcn@latest add @diceui/sortable

Layout

Import the parts, and compose them together.

import {
  Sortable,
  SortableContent,
  SortableItem,
  SortableItemHandle,
  SortableOverlay,
} from "@/components/ui/sortable";
 
return (
  <Sortable>
    <SortableContent>
      <SortableItem>
        <SortableItemHandle />
      </SortableItem>
      <SortableItem />
    </SortableContent>
    <SortableOverlay />
  </Sortable>
)

Every part accepts a render prop, so an item can be composed with your own element or component instead of the default div.

<SortableItem value={item.id} render={<Card />}>
  {item.name}
</SortableItem>

Usage

With Primitive Values

When using primitive arrays (strings, numbers), the getItemValue prop is optional. The component will automatically use the item itself as the unique identifier.

const [items, setItems] = React.useState(["Item 1", "Item 2", "Item 3"]);
 
<Sortable value={items} onValueChange={setItems}>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item} value={item}>
        {item}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>

With Object Arrays

When using object arrays, the getItemValue prop is required to extract a unique identifier from each item.

const [items, setItems] = React.useState([
  { id: 1, name: "Item 1" },
  { id: 2, name: "Item 2" },
]);
 
<Sortable
  value={items}
  onValueChange={setItems}
  getItemValue={(item) => item.id}
>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item.id} value={item.id}>
        {item.name}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>

Examples

With Dynamic Overlay

Display a dynamic overlay when an item is being dragged.

With Handle

Use SortableItemHandle as a drag handle for sortable items.

With Primitive Values

Use an array of primitives (string or number) instead of objects for sorting.

API Reference

Sortable

The main container component for sortable functionality.

SortableContent

Container for sortable items. Multiple SortableContent components can be used within a Sortable component.

SortableItem

Individual sortable item component.

SortableItemHandle

A button component that acts as a drag handle for sortable items.

The component renders a button and adds the following styles:

• select-none for pointer events
• cursor-grab when not dragging (unless flatCursor is true)
• cursor-grabbing when dragging (unless flatCursor is true)
• cursor-default when flatCursor is true

SortableOverlay

The overlay component that appears when an item is being dragged.

Accessibility

Keyboard Interactions