Sortable list

When to use #

Use it for

Priorities, steps and playlists the person orders.
Lists that must be reorderable by keyboard too.

Skip it when

Order is automatic; use a plain list.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/sortable-list.json

Adds its 5 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { useState } from "react"
import { SortableList } from "@/components/ui/sortable-list"

export function PriorityList() {
  const [items, setItems] = useState([
    { id: "review", label: "Review accessibility" },
    { id: "notes", label: "Write release notes" },
    { id: "handoff", label: "Prepare handoff" },
  ]);
  return (
    <div className="w-full max-w-sm">
      <SortableList label="Launch tasks" items={items} onItemsChange={setItems} />
    </div>
  );
}

API reference #

SortableList

component

PropTypeDefault

label *string—

items *readonly T[]—

onItemsChange *(items: T[]) => void—

renderItem((item: T) => ReactNode)—

disabledbooleanfalse

classNamestring—

It exposes status semantics, with aria-label, aria-describedby and aria-hidden kept in step with state. Changes that matter are announced through a live region.

KeyBehaviour

HomeJumps to the first item or the minimum.

EndJumps to the last item or the maximum.

↑Moves to the previous item or value.

EscapeCloses or cancels, then returns focus to where it came from.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.