Sortable List

"use client"

import * as React from "react"

Use a sortable list when people set their own order, such as the sections on a home screen, the accounts in a switcher or the contacts to notify first. Each row has a drag handle, an optional action and a muted state, and two lists that share a drag type can exchange rows for show and hide. Pick a plain Item list when the order is fixed.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/sortable-list
Copy

Usage#

Copyimport { SortableList, SortableListItem } from "@/components/ui/sortable-list"

Copyconst [accounts, setAccounts] = React.useState([
  { id: "main", name: "Main account" },
  { id: "savings", name: "Savings" },
])
 
<SortableList
  aria-label="Account order"
  items={accounts}
  getItemText={(account) => account.name}
  onReorder={setAccounts}
>
  {(account) => (
    <SortableListItem id={account.id} textValue={account.name} />
  )}
</SortableList>

The list is controlled. It reports the new order through onReorder and renders the items you pass back.

Composition#

CopySortableList
└── SortableListItem
    ├── leading
    ├── title and description
    ├── action
    └── drag handle

Features#

• Built on React Aria GridList drag and drop
• Drag a row with the pointer or a finger, or focus its handle and use the keyboard
• Screen readers announce where a row is picked up and dropped
• A leading slot, a description line and an action slot on every row
• A muted state for rows in a "Hidden" group
• Lists that share a dragType accept each other's rows
• An empty state that is also a drop target
• isDragDisabled to lock the order, for example while saving

Show and hide#

Give two lists the same dragType and handle onInsert on both. Rows can be dragged between them, and each row's action button moves it without dragging. Set muted on the hidden rows.

"use client"

import * as React from "react"

Copy<SortableList
  aria-labelledby={hiddenLabel}
  items={hidden}
  dragType="application/x-home-sections"
  onReorder={setHidden}
  onInsert={(keys, index) => moveTo("hidden", keys, index)}
  renderEmptyState={() => "Nothing hidden"}
>
  {(section) => (
    <SortableListItem id={section.id} textValue={section.title} muted />
  )}
</SortableList>

onInsert receives the dragged keys and the index they were dropped at. Remove the rows from the source list and insert them into the target list there.

Locked order#

Set isDragDisabled to turn dragging off. Rows cannot be dragged until it is turned back on.

"use client"

import * as React from "react"

Accessibility#

React Aria renders the list as a grid with one row per item. The pointer drags the whole row, while the handle is a real button and the keyboard and screen reader entry point: focus it, press Enter, move to a drop position and press Enter again to drop, or Escape to cancel. Drops are announced. Row actions, such as the hide and show buttons, give keyboard users a second way to move rows between lists.

Name the list#

Give every list a name with aria-label, or with aria-labelledby pointing at a visible heading.

Copy<SortableList aria-label="Contact order" items={people} onReorder={setPeople}>
  {/* rows */}
</SortableList>

Give rows a text value#

textValue is required. React Aria reads it in the handle's name and in drag announcements, so it should match the visible title.

Label row actions#

Action buttons are usually icon-only. Give each an aria-label with the action and the row.

Copy<Button variant="ghost" size="icon-sm" aria-label={`Hide ${section.title}`}>
  <EyeOffIcon />
</Button>

API Reference#

SortableList#

The list. Renders a React Aria GridList with a stack layout and accepts its other props, such as aria-label and aria-labelledby.

T is any object with an id of type Key (a string or a number).

SortableListItem#

One row with a drag handle at the end. Renders a React Aria GridListItem and accepts its other props.