Skip to content

Sortable List

A list that users reorder by dragging or with the keyboard.

Freeze the release branch

Cut v2.4 from main

TS
Write the release notes

Changes since v2.3

AP
Deploy to staging

Run the smoke tests

SR
Announce the release

Blog post and changelog

PS

Installation

  1. Add the registryOnce per project
  2. Add sortable-list

Usage

Pass your items to SortableList as value, and render a SortableListItem for each one, in the same order, with the item's unique value. For strings and numbers, that's the item itself; otherwise it's the item's id. Pass getItemValue to use a different value. When an item is dropped in a new place, onValueChange receives the items in their new order. To let the list keep track of its own order instead, pass the items as defaultValue, and pass children a function that renders a SortableListItem for an item. SortableList calls it for each item in the current order.

Users drag an item by its SortableListHandle, or by the whole item when it has no handle. As an item moves, the others slide aside to make room, and the item settles into place when it's dropped. Dragging an item near the edge of a scrolling area scrolls it, whether that's the page, a container around the list, or the list itself.

Each handle, or each item without one, is a stop in the tab order. Space or Enter picks an item up, the arrow keys along the list move it, and Home and End move it to the start or end. Space or Enter drops it, and Escape or moving focus away returns it to where it was. Screen readers that activate controls with a click, as VoiceOver and TalkBack do, pick up and drop an item the same way. Screen readers announce the item's position as it moves. label on a SortableListItem sets the name they announce for it, in place of its text.

SortableList lays the items out in a column, or in a row with orientation="horizontal", and doesn't style them. Render each one as an Item, or anything else with a background, since a lifted item passes over the others. SortableList has the list role and its items the listitem role, except when it's rendered as part of a table or its items have no handles, since an item without a handle is a button.

Composition

Examples

Without a handle

Leave out SortableListHandle to drag the whole item. On a touch screen, users press and hold the item for a moment before dragging, so swiping across the list still scrolls the page. Without a handle, the item is a button, which screen readers read as a single element, so keep other controls out of it.

1
Faster page loads
2
Offline support
3
Dark mode
4
Keyboard shortcuts
5
Two-factor sign-in

Horizontal

orientation="horizontal" lays the items out in a row, and the left and right arrow keys move an item along it.

Name
Status
Owner
Due

Columns show in the order Name, Status, Owner, Due.

Interactive content

Give an item a SortableListHandle when it holds buttons, switches, links or fields. The controls then work as usual, and the handle moves the item.

Push

On this device

Email

tony@example.com

Text message

Ending in 4242

Slack

#alerts

Disabled

disabled on a SortableListItem keeps that item where it is while the others move around it. disabled on SortableList keeps every item in place.

Inbox
Today
Upcoming
Projects
Archive

Table rows

Render SortableList as a Table's TableBody, and each item as a TableRow. SortableList then leaves the layout and the roles to the table, with or without handles. A row's border depends on its position in the table, which only changes on drop, so this example gives every row a border while one is lifted.

In a form

Give a Field or SortableList a name, and each item's value submits under it in order, so formData.getAll(name) returns the ranking. Pass form with a form's id when the list sits outside the form. With a Form, onFormSubmit receives the values as an array. A FieldLabel labels the list, and screen readers read the field's description and errors with it. An item that's mid-drag submits in its original position until it's dropped.

A form reset restores the items' original order. When that changes the order, the reset calls onValueChange with the reason none, so the parent of a controlled list decides whether to apply it. A disabled SortableList still submits its order. This example manages its own order with defaultValue.

Dark mode
Offline sync
Shared folders
Keyboard shortcuts

Put the one you want most first.

Scrolling

A list in a Scroll Area scrolls while an item is dragged near its top or bottom, and moving an item with the keyboard keeps it in view.

Saving the order

onValueChange runs once per drop, and only when the order changed. eventDetails.reason is drag or keyboard, depending on how the item moved. eventDetails.item, from and to give the item that moved and its index before and after, so you can save the move. Calling eventDetails.cancel() slides the item back. Otherwise, the items hold their new places while they wait for the new order, so it can arrive a moment later, such as from a transition. If it hasn't arrived after a second, the items slide back.

Revenue
Active users
Conversion
Churn

Move a metric to save the order.

Props

SortableListHandle shows a grip icon, rotated to match the list's orientation, unless you pass it your own children. An item has a data-dragging attribute while it's lifted, and data-dropping while it settles. SortableList also has data-dragging while an item is lifted, set to pointer or keyboard depending on how the item was picked up.

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

SortableList

SortableListItem

SortableListHandle