# Draggable Sortable

Source: https://payloadcms.com/docs/beta/ui-components/draggable-sortable

Use `DraggableSortable` with `DraggableSortableItem` to add pointer, touch, and keyboard reordering to custom Admin Panel interfaces.

## Import

```tsx
import { DraggableSortable, DraggableSortableItem } from '@payloadcms/ui'
```

## Basic usage

**Implementation**

```tsx
'use client'

import {
  Button,
  ChevronIcon,
  DraggableSortable,
  DraggableSortableItem,
  DragHandleIcon,
} from '@payloadcms/ui'
import { useState } from 'react'

const initialItems = [
  { id: 'overview', label: 'Overview' },
  { id: 'details', label: 'Details' },
  { id: 'settings', label: 'Settings' },
]

const moveItem = (items, moveFromIndex, moveToIndex) => {
  const nextItems = [...items]
  const [movedItem] = nextItems.splice(moveFromIndex, 1)
  nextItems.splice(moveToIndex, 0, movedItem)
  return nextItems
}

export function SortableList() {
  const [items, setItems] = useState(initialItems)

  return (
    <DraggableSortable
      className="sortable-list"
      ids={items.map(({ id }) => id)}
      onDragEnd={({ moveFromIndex, moveToIndex }) => {
        setItems((current) => moveItem(current, moveFromIndex, moveToIndex))
      }}
    >
      {items.map(({ id, label }, index) => (
        <DraggableSortableItem id={id} key={id}>
          {({ attributes, isDragging, listeners, setNodeRef, transform, transition }) => (
            <div
              className="sortable-item"
              ref={setNodeRef}
              style={{ opacity: isDragging ? 0.6 : 1, transform, transition }}
            >
              <span>{label}</span>
              <div className="sortable-actions">
                <Button
                  aria-label={`Move ${label} up`}
                  buttonStyle="ghost"
                  disabled={index === 0}
                  icon={<ChevronIcon direction="up" size={16} />}
                  margin={false}
                  onClick={() => setItems((current) => moveItem(current, index, index - 1))}
                />
                <Button
                  aria-label={`Move ${label} down`}
                  buttonStyle="ghost"
                  disabled={index === items.length - 1}
                  icon={<ChevronIcon direction="down" size={16} />}
                  margin={false}
                  onClick={() => setItems((current) => moveItem(current, index, index + 1))}
                />
                <Button
                  aria-label={`Drag to reorder ${label}`}
                  buttonStyle="ghost"
                  extraButtonProps={{ ...attributes, ...listeners }}
                  icon={<DragHandleIcon />}
                  margin={false}
                />
              </div>
            </div>
          )}
        </DraggableSortableItem>
      ))}
    </DraggableSortable>
  )
}
```

**Styling**

Style the list and row wrappers while leaving the drag transform and transition inline on each item. Payload theme variables keep the surface consistent across light and dark modes.

```css
.sortable-list {
  display: grid;
  gap: var(--spacer-2);
}

.sortable-item {
  align-items: center;
  background: var(--color-bg-secondary);
  border: 1px solid var(--color-border);
  display: flex;
  justify-content: space-between;
  padding: var(--spacer-2) var(--spacer-3);
}
```

- `--color-bg-secondary`: Sortable item background.
- `--color-border`: Sortable item border.
- `--spacer-2`: Spacing within and between items.

`DraggableSortable` coordinates the list and reports the original and destination indexes through `onDragEnd`. Your component remains responsible for updating local state and persisting the new order when necessary.

Each `DraggableSortableItem` exposes the attributes, listeners, ref, transform, and transition needed to render an item. Apply the listeners to a visible drag handle so the rest of the row can retain its own interactions.

## DraggableSortable props

| Prop          | Type                                              | Description                                    |
| ------------- | ------------------------------------------------- | ---------------------------------------------- |
| `children*`   | `ReactNode`                                       | Renders the sortable items.                    |
| `ids*`        | `string[]`                                        | Lists item IDs in their current display order. |
| `onDragEnd*`  | `({ moveFromIndex, moveToIndex, event }) => void` | Handles a completed reorder.                   |
| `onDragStart` | `({ id, event }) => void`                         | Handles the beginning of a drag.               |
| `className`   | `string`                                          | Adds a class to the sortable list container.   |

## DraggableSortableItem props

| Prop        | Type                           | Description                                                 |
| ----------- | ------------------------------ | ----------------------------------------------------------- |
| `id*`       | `string`                       | Matches an entry in the parent `ids` array.                 |
| `children*` | `(sortableState) => ReactNode` | Renders the item with its drag attributes and visual state. |
| `disabled`  | `boolean`                      | Prevents the item from being reordered.                     |

_\* An asterisk denotes that a prop is required._

## Accessibility

- Put the supplied attributes and listeners on a keyboard-focusable drag handle.
- Give the handle an accessible name that identifies the item it moves.
- Provide move-up and move-down controls so pointer users can reorder without a dragging movement.
- Persist the resulting order only after `onDragEnd` supplies a valid destination.

These components configure their own drag-and-drop context and require no Payload providers.
