Sortable lists and trees
Drag an item or pick it up with Space, move a selection together, and nest rows in a tree by moving them sideways. Every move is read out.
Rank what to build next
Space picks an item up, the arrow keys move it, Space drops it and Escape puts it back.
First: Faster search
Playlist
Space picks an item up, the arrow keys move it, Space drops it and Escape puts it back. Shift+Space selects items to move together, and Shift with the arrow keys selects a run.
Select a few with Shift+Space or their checks, then move them together.
Project files
Arrow keys move between rows; Right opens a branch and Left closes it. Space picks a row up with what's under it, Up and Down move it, Left and Right change its level, Space drops it and Escape puts it back.
Nothing moved yet.
Lists and trees people put in order. SortableList is a ranking, a playlist or a set of
steps: drag an item by its grip, or pick it up with Space and move it with the arrow keys.
It's built on UI SDK's createReorder, so every step is read out, and on createSelection,
so several items can move together. SortableTree is an outline, a page tree or layers:
rows move up and down and sideways to change their level, with what's under them, on UI
SDK's createTreeReorder.
pnpm dlx shadcn@latest add @uiset/sortable-list @uiset/sortable-treeParts
| Part | Item | What it is |
|---|---|---|
SortableList | sortable-list | A list drawn from items that people put in order |
SortableListRoot, SortableListItemPart | sortable-list | Its parts, for items drawn your own way |
sortableList | sortable-list | The primitive, for another framework |
SortableTree | sortable-tree | A tree drawn from nested items that people reorder and nest |
SortableTreeRoot, SortableTreeRowPart | sortable-tree | Its parts, for rows drawn your own way |
sortableTree, flatten, build | sortable-tree | The primitive, and nested items to rows and back |
Sortable list
import { SortableList } from "@/components/ui/sortable-list"
const features = [
{ value: "search", label: "Faster search" },
{ value: "offline", label: "Offline mode" },
{ value: "export", label: "Export to PDF" },
]
const [order, setOrder] = useState(features.map((f) => f.value))
<SortableList label="Priorities" items={features} value={order} onValueChange={setOrder} numbered />
labelis required: it names the list for people and agents.itemsare{ value, label, description?, locked? }.valueis the key;labelnames the item when it's read out.valuewithonValueChange(order, details)controls the order, as the items' keys, ordefaultValuestarts it. Without either, it starts initems' order. An item added toitemsjoins the end; one taken out leaves the order.details.reasonisdrag,move-keyorimperative.multiplelets people select several items and move them together.selectedwithonSelectedChange, ordefaultSelected, holds the selection. Each item gets a check to press, and a dragged selection's copy shows how many it carries.lockedon an item means it can't be picked up or selected, and it shows a lock in place of its grip. Other items can still move past it.numberedshows each item's place, 1 first, updated as an item moves.orientationisvertical(the default),horizontalfor a row that wraps, like tags, orgridfor tiles. Set it once.renderItem(item, state)draws an item's face in place of its label and description.statehasmoving,dragging,selectedandlocked.helpreplaces the instructions read out with the list.
A dragged item's copy follows the pointer while the item itself shows where it will land, and a list in a scroll area scrolls when the copy nears its edge. On a touch screen, an item drags from its grip, so a finger elsewhere still scrolls the page.
Items carry data-moving while they're picked up, data-dragging while a pointer drags
them, and data-selected. The list has data-moving during a move and data-orientation.
Sortable tree
import { SortableTree, type SortableTreeItem } from "@/components/ui/sortable-tree"
const [pages, setPages] = useState<SortableTreeItem[]>([
{ value: "guides", label: "Guides", children: [{ value: "install", label: "Installation" }] },
{ value: "api", label: "API", children: [] },
{ value: "faq", label: "FAQ" },
])
<SortableTree label="Pages" items={pages} onItemsChange={setPages} defaultExpanded={["guides"]} />
labelis required: it names the tree for people and agents.itemsare nested{ value, label, children?, locked? }. An item withchildrenis a branch, even with none yet (children: []); only branches hold other items.itemswithonItemsChange(items, details)controls the tree, ordefaultItemsstarts it.onItemsChangeruns once, when a move is dropped, with the items nested again; each keeps its own fields.detailshaskey(what moved),parent(its new branch, ornullat the top) andindex(its place there, from 0), andreason.expandedwithonExpandedChange, ordefaultExpanded, holds the open branches. A branch something is dropped into opens, so the row stays in view, and a branch a row is carried into shows open while it's there.- A row dropped inside an item that isn't a branch goes back, and the reason is read out;
while it's carried there, it's marked in the danger tone.
refusedMessagewords that. maxDepthlimits how deep an item and those under it go, from 0.lockedon an item means it can't be picked up.onAction(key)runs for Enter or a press on an item that isn't a branch, like opening a page. Branches open and close instead.iconsadds folder and file icons.renderItem(item, row)draws a row's face after its arrow;rowhasdepth,branch,expanded,position,size,moving,draggingandinvalid.
Rows are drawn flat, indented --sortable-tree-indent (20px) a level, which is also how far
a drag goes sideways for each level. They carry data-branch, data-moving,
data-dragging and data-invalid; each grip shows on hover and focus, and always on a
touch screen, where a row drags from it.
Keys
| Keys | Where | Does |
|---|---|---|
| Up, Down (Left, Right in a row) | a sortable list | Move between items. The list is one tab stop |
| Home, End | a sortable list | The first and last item |
| Letters | a sortable list | The next item whose name starts with them |
| Space, Enter | an item | Pick it up, or drop it where it is |
| Arrows, Home, End | an item that's picked up | Move it one place, or to either end |
| Escape | an item that's picked up | Put it back where it was |
| Tab | an item that's picked up | Put it back, and move on |
| Shift+Space | a list with multiple | Select or let go of the item |
| Shift with the arrows | a list with multiple | Select the run of items to the one you reach |
| Ctrl+A (Command+A on a Mac) | a list with multiple | Select every item that can move, or none |
| Escape | a list with a selection | Let go of the selection |
| Up, Down, Home, End | a sortable tree | Move between the rows that show. The tree is one tab stop |
| Right | a branch | Open it, or go to its first item if it's open |
| Left | a row | Close a branch that's open, or go to the row's branch |
| Enter | a row | Open or close a branch; onAction on anything else |
| Space | a row | Pick it up with everything under it, or drop it |
| Up, Down | a row that's picked up | Move it between the rows that show |
| Left, Right | a row that's picked up | Take it out a level, or in one |
| Escape | a row that's picked up | Put it back where it was |
With a pointer: drag an item. With multiple, press an item's check, or Shift-click,
Command-click or Control-click it, to select; dragging a selected item carries the selection.
In a tree, drag a row up or down, and sideways a level for every 20px; a press on a branch
opens or closes it. In right-to-left text, Left and Right swap.
For agents
- SortableList is listed by its
label, with each item as data ({ value, label, position }).moveItem(item, position)moves an item, by its key or its label, to a place counted from 1; pass a list of items to move several, in their order.selectItems(items)sets the selection, withmultiple. Moving a locked item, or a name the list doesn't have, fails and says why. - SortableTree is listed by its
label, with each item's level and branch.moveItem(item, into, position)moves an item and what's under it into a branch (nullfor the top level), at a place from 1 (the end without one).expandItemandcollapseItemopen and close branches, andopenItemrunsonAction. A move into an item that isn't a branch, into itself, or of a locked item fails and says why.
Web Components
<uiset-sortable-list> and <uiset-sortable-tree> are in
Web Components, on the same primitives:
<uiset-sortable-list id="playlist" label="Playlist" multiple></uiset-sortable-list>
const playlist = document.querySelector("uiset-sortable-list")! // typed by @uiset/web
playlist.items = [
{ value: "intro", label: "Intro", description: "0:48", locked: true },
{ value: "harbor", label: "Harbor Lights", description: "3:52" },
]
playlist.addEventListener("valuechange", (e) => save(e.detail.value)) // preventDefault() refuses
itemsis a property.value(the order) andselectedare live: reading gives a copy, and setting them fires nothing. Keys a set order leaves out follow it, initems' order.label,multiple,numbered,orientationandhelpare attributes.- It fires
valuechangeandselectedchange, andapihasmoveItemandselectItems.
<uiset-sortable-tree id="pages" label="Pages" icons></uiset-sortable-tree>
const pages = document.querySelector("uiset-sortable-tree")!
pages.items = [{ value: "guides", label: "Guides", children: [] }, { value: "faq", label: "FAQ" }]
pages.expanded = ["guides"]
pages.addEventListener("itemschange", (e) => save(e.detail.value)) // the items, nested again
itemsandexpandedare live: after a move,itemsreads the tree as it is. Setting them fires nothing.label,icons,max-depthandhelpare attributes.- It fires
itemschange,expandedchangeandaction, andapihasmoveItem,expandItem,collapseItemandopenItem.