Loading…

Reorder List

beta

A short list of people or things you put in order by dragging liquid pills, or with Space and the arrow keys.

Forms
1 file
2 npm packages
Accessibility notes
Animates with motion

Playground

Installation

The CLI installs avatar as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add reorder-list

npm packages installed: class-variance-authority, motion.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { ReorderList } from "@/components/ui/reorder-list";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Presence
Controlled
Localised
Custom Rows
Disabled

API

Generated from the component's own types, so a prop cannot appear here without existing.

<ReorderList>

Prop	Type	Default
`items` (required)	`ReorderListItem[]`	—
`announcements` Overrides for the live-region messages (i18n).	`Partial<ReorderListAnnouncements>`	—
`corner` Pill corner radius, 0–22 px.	`number`	`22`
`defaultValue` Initial order (uncontrolled). Defaults to the order of `items`.	`string[]`	—
`disabled`	`boolean`	`false`
`fill`	`"light" \| "dark"`	`"light"`
`give` Spring softness for rows settling, 0–100.	`number`	`50`
`instructions` Describes the keyboard operation; referenced by every row's button.	`string`	`"Press Space or Enter to pick up, the arrow keys to move, Space or Enter to drop, Escape to cancel."`
`lean` How much the held pill skews and squashes with velocity, 0–100.	`number`	`18`
`onValueChange` Called with the new order after a drop that changed it.	`(value: string[]) => void`	—
`renderItem` Replaces the avatar and label inside a row. The label still names the button.	`(item: ReorderListItem, state: { grabbed: boolean; index: number }) => ReactNode`	—
`stroke` 1px inset hairline on each pill.	`boolean`	`false`
`value` Order as item ids (controlled).	`string[]`	—

Plus every attribute of <div> except defaultValue, children.

Accessibility

A real list (ol, role=list, named by aria-label) whose rows are buttons named by their label and described by the keyboard instructions. Space or Enter picks a row up (aria-pressed), ArrowUp/ArrowDown or Home/End move it, Space or Enter drops it and Escape (or leaving the row) cancels and restores the original order; without a grab the arrows move focus between rows. Focus stays on the moved row. A polite, visually hidden status region announces each grab, move, drop and cancel (messages overridable for i18n), including drops made by pointer. The goo layer of pill backgrounds is aria-hidden and separate from the text, and avatars are decorative. Under reduced motion nothing deforms and rows jump to their slots.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

items

ReorderListItem[]

—

announcements

Overrides for the live-region messages (i18n).

Partial<ReorderListAnnouncements>

—

corner

Pill corner radius, 0–22 px.

number

22

defaultValue

Initial order (uncontrolled). Defaults to the order of items.

string[]

—

disabled

boolean

false

fill

"light" | "dark"

"light"

give

Spring softness for rows settling, 0–100.

number

50

instructions

Describes the keyboard operation; referenced by every row's button.

string

"Press Space or Enter to pick up, the arrow keys to move, Space or Enter to drop, Escape to cancel."

lean

How much the held pill skews and squashes with velocity, 0–100.

number

18

onValueChange

Called with the new order after a drop that changed it.

(value: string[]) => void

—

renderItem

Replaces the avatar and label inside a row. The label still names the button.

(item: ReorderListItem, state: { grabbed: boolean; index: number }) => ReactNode

—

stroke

1px inset hairline on each pill.

boolean

false

value

Order as item ids (controlled).

string[]

—