- Add the registry
- 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.
Horizontal
orientation="horizontal" lays the items out in a row, and the left and right arrow keys move an
item along it.
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.
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.
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.
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.
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.