Sortable List

A list you reorder by dragging a handle, or entirely from the keyboard, with every move announced.

Ship onboarding redesignDesign
Fix checkout timeoutPayments
Migrate search indexPlatform
Write Q3 roadmapProduct

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

Part of Lathe Pro. Set up your project once with your license key: npx latheui init --key <key>. See Lathe Pro.

Sortable List is part of Lathe Pro

The preview is live and free to try. The source, the install and every assembly come with Pro: $79 once, with lifetime updates.

Get Pro I have Pro

Depends on

lucide-react
motion
lathe/motion

API reference

SortableList<T>

Controlled only: it renders the order you give it.

Prop	Type	Default	Description
items* (required)	T[]	—	Items in their current order.
onReorder* (required)	(items: T[]) => void	—	Called with the new order as items move.
getId* (required)	(item: T) => string	—	Stable, unique id for an item.
getLabel* (required)	(item: T) => string	—	Plain-text name, used for the handle's name and for announcements.
renderItem* (required)	(item: T, state: { dragging: boolean }) => ReactNode	—	Row content. dragging is true while the row is lifted.
label* (required)	string	—	Accessible name of the list.
className	string	—	Classes for the list.
itemClassName	string	—	Classes for each row.

Keyboard

Tab: Moves between the reorder handles (and any controls in the rows).
SpaceEnter: Grabs the item, or drops it if it is already grabbed.
ArrowUpArrowDown: Moves the grabbed item one position.
HomeEnd: Moves the grabbed item to the top or bottom.
Escape: Cancels and returns the item to where it started.

Accessibility

Everything that can be done by dragging can be done from the keyboard. Drag and drop is never the only way to reorder.
Grabbing, each move, dropping and cancelling are announced with the item's name and its position, such as “moved to position 2 of 4”.
Each handle is a button named “Reorder” plus the item's label, with the instructions attached as its description.
The handle is the only drag target. That leaves the row free for other controls and lets the page scroll normally when a finger lands on a row.
Focus stays on the handle as the item moves, and moving focus away drops the item in place.

Motion

A lifted row scales to 102% and gains a shadow. The other rows move out of the way with the smooth spring.
With reduced motion, rows swap places instantly and the lifted row does not scale. The shadow still shows which row is held.

Customization

React to the lifted state

renderItem={(item, { dragging }) => (
  <span className={dragging ? "font-medium" : undefined}>{item.title}</span>
)}

Save when the order settles

onReorder fires on every swap while dragging. Debounce it, or save on a separate effect.

React.useEffect(() => {
  const timer = setTimeout(() => saveOrder(items.map((item) => item.id)), 600)
  return () => clearTimeout(timer)
}, [items])

API reference

SortableList<T>

Controlled only: it renders the order you give it.

Prop	Type	Default	Description
items* (required)	T[]	—	Items in their current order.
onReorder* (required)	(items: T[]) => void	—	Called with the new order as items move.
getId* (required)	(item: T) => string	—	Stable, unique id for an item.
getLabel* (required)	(item: T) => string	—	Plain-text name, used for the handle's name and for announcements.
renderItem* (required)	(item: T, state: { dragging: boolean }) => ReactNode	—	Row content. dragging is true while the row is lifted.
label* (required)	string	—	Accessible name of the list.
className	string	—	Classes for the list.
itemClassName	string	—	Classes for each row.

Accessibility

Everything that can be done by dragging can be done from the keyboard. Drag and drop is never the only way to reorder.
Grabbing, each move, dropping and cancelling are announced with the item's name and its position, such as “moved to position 2 of 4”.
Each handle is a button named “Reorder” plus the item's label, with the instructions attached as its description.
The handle is the only drag target. That leaves the row free for other controls and lets the page scroll normally when a finger lands on a row.
Focus stays on the handle as the item moves, and moving focus away drops the item in place.

Customization

React to the lifted state

renderItem={(item, { dragging }) => (
  <span className={dragging ? "font-medium" : undefined}>{item.title}</span>
)}

Save when the order settles

onReorder fires on every swap while dragging. Debounce it, or save on a separate effect.

React.useEffect(() => {
  const timer = setTimeout(() => saveOrder(items.map((item) => item.id)), 600)
  return () => clearTimeout(timer)
}, [items])

API reference

SortableList<T>

Keyboard

Accessibility

Motion

Customization

React to the lifted state

Save when the order settles

Related

API reference

SortableList<T>

Keyboard

Accessibility

Motion

Customization

React to the lifted state

Save when the order settles

Related