Skip to contentKino
Skip to Content

Sortable list

A list put in a new order by dragging an item from anywhere on it, except a control inside it, by touch with a long press, and by keyboard from its handle. Its neighbours glide aside as it passes, each move is announced, and it works as a column or as a wrapping grid.

npx shadcn add https://kinoui.com/r/sortable-list.json
Share on

Examples

Launch priorities

Kino 2.0 · the team works from the top down
AOShip the new pricing pageNov 18
LFRewrite onboarding emailsNov 19
KWMove billing to annual plans, with prorated credit for teams that switch mid-cycleNov 21
KWSpeed up workspace searchNov 24
TLCSV export for reportsNov 26
AOSAML single sign-onDec 2

Default

Give it the order as value and keep the new one from onValueChange, which runs once an item is dropped in a new place. Drag a row from anywhere, or focus its handle and press Space.

Pinned views

Shown on everyone’s home, in this order
Inbox12 items
Launch board34 items
Release calendar8 items
Roadmap21 items
Design team5 items
Starred17 items

Grid

layout='grid' puts items in rows that wrap, laid out by className; the arrow keys move a picked-up item along a line and between lines.

Doing3

Ship the new pricing page
KINO-142Nov 18AO
Rewrite onboarding emails
KINO-151Nov 19LF
Speed up workspace search
KINO-163Nov 24KW

Controls inside

A press on a button, a link, a checkbox or any other control inside an item does what it says; a press anywhere else drags.

MCMaya Chen
TATomás Alvarez
PRPriya Raman

Items that come and go

Items added or removed take their place in the order, and the others glide to make room or close the gap.

Backlog

12 issues
High priorityKINO-201Audit log for adminsAO
Medium priorityKINO-188Dark mode for email digestsLF
High priorityKINO-215Bulk edit labelsKW
Medium priorityKINO-176Recurring tasksTL
Low priorityKINO-219Slack thread syncKW
Medium priorityKINO-194Custom fields on projectsAO
Low priorityKINO-203Keyboard shortcuts sheetLF
Low priorityKINO-181Archive old projectsTL
High priorityKINO-222Guest accessAO
High priorityKINO-209Two-factor recovery codesKW
Medium priorityKINO-198Saved filtersLF
Low priorityKINO-212Time zones on due datesTL

In a box that scrolls

Dragged to the edge of a box that scrolls, the box scrolls; picked up by keyboard, the item stays in view as it moves.

Bug
Customer request
UI
Needs design review before release
API
Docs
Mobile
Performance

Different widths

Without value, the list keeps its own order. Items of any width wrap and glide across lines.

Approval order

Expenses over $5,000 · set by your workspace admin
TLTobias LindqvistProduct
AOAmara OkaforLead
BHBen HartleyFinance

Disabled

disabled keeps the order as it is: nothing drags, and the handles go.

Installation

npx shadcn@latest add https://kinoui.com/r/sortable-list.json
Files
lib/refs.tslib/reduce-motion.tslib/resize.tslib/swap.tsxcomponents/kino/spinner.tsxcomponents/kino/button.tsxlib/announce.tsxlib/controllable.tslib/run-progress.tslib/highlight.tslib/flow.tslib/scroll.tslib/sort.tsxcomponents/kino/sortable-list.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

SortableList

PropTypeDefaultDescription
valuestring[]NoneThe items’ values, in order. Leave it out for a list that keeps its own order.
defaultValuestring[]NoneThe order to start from, when value is left out. Without either, the order the items are given in.
onValueChange(value: string[]) => voidNoneCalled with the new order once an item is dropped in a new place: not while it moves, and not when the move is cancelled.
layout'list''grid''list'A column, or items in rows that wrap: Up and Down then move between lines, and Left and Right along one.
disabledbooleanfalseKeeps the order as it is: nothing drags, and the handles go.

SortableItem

PropTypeDefaultDescription
valuestringNoneWhat the order holds for it. Unique in the list.
labelstringNoneIts name, which a screen reader hears as it moves (“Ship the new pricing page moved to position 3 of 6”) and which names its handle (“Move Ship the new pricing page”).
disabledbooleanfalseIt can’t be dragged, and its handle turns off and dims; the others can still move past it.

Data attributes

AttributeOnDescription
data-liftedSortableItempointer or keyboard while the item is picked up, and how.
data-settlingSortableItemWhile a dropped item glides into its place. It stays above its neighbours until then.
data-pressingSortableItemWhile a finger holds the item, before it lifts.
data-sortingThe list (data-slot="sortable-list-items")While any of its items is picked up.

Accessibility

  • The list is a list and each item a list item. Each item’s handle is a button named “Move” and the item’s label, which describes how to move it.
  • Space or Enter on the handle picks the item up and drops it; the arrow keys move it, Home and End take it to the ends, Escape puts it back where it was, and Tab drops it where it is. A screen reader’s activate command picks it up and drops it as Space does.
  • Focus stays on the handle as its item moves, and the item is scrolled into view.
  • A polite status region says each pick-up, move, drop and cancel, with the item’s position (“moved to position 3 of 6”).
  • A picked-up item shows it with a raised shadow and its handle pressed (aria-pressed), and with an outline in forced colours, where shadows go.
  • A press on a control inside an item, such as a button, a link, a checkbox or a field, goes to the control and never starts a drag.