useListReorder@astryxdesign/core v0.7.5 · useListReorder

Usage

Experimental: this hook and everything exported from @astryxdesign/core/List/experimental are outside the stable compatibility promise and may change or be removed in a patch release. The reorder session of core List (onReorder), for a list whose rows are not ListItems, such as rows of form fields. Put a ListReorderHandle in each row (named “Reorder {label}”, or by its aria-label; isDisabled keeps it focusable but inert); a row that keeps its place carries LIST_REORDER_FIXED_ROW_ATTRIBUTE and no handle, and no row moves past it. A finger held still on a handle for a moment picks its row up (a flick on it scrolls, a pinch zooms); the row follows the finger, the rows it passes slide out of its way on UIKit’s table spring, the list autoscrolls near its edges, and the drop springs the row into its slot. A mouse drags at once, without motion. A focused handle’s arrow keys, Home and End move its row, Space picks it up and Escape puts it back, and screen readers hear each move.

ts
import {useListReorder} from '@astryxdesign/core/List'

Best practices

GuidancePractices
Do

Use core List with onReorder when the rows are ListItems; reach for this hook only when they cannot be.

Do

Commit the new order synchronously in onReorder, keeping each row’s key, so the drop settles from where the row is.

Don't

Animate the rows’ translate yourself while a session can move them, or wrap the list in a View Transition for the drop.

Don't

Rely on this API from stable product code: it is experimental and may change in a patch release.

Parameters

ParamTypeDescription
listRefrequired
RefObject<HTMLElement | null>

The list element. Its direct children are the rows, in order; each row is an li (or contains its handle inside one).

onReorderrequired
((fromIndex: number, toIndex: number) => void) | undefined

Called once per move with the row’s old and new index. Commit the new order in the same task, rows keyed by item. Without it the session is off and ListReorderHandle renders nothing.

hintIdrequired
string

The id of an element holding the reorder instructions (the @astryx.list.reorderHint string); every handle is described by it.

Returns

FieldTypeDescription
session
| null

The reorder session, opaque; null without onReorder. Provide it with <ListReorderContext value={session}> around the rows.

Use with shadcn

Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.

This install URL expires with the draft preview.
bash
npx shadcn@4.19.0 add https://astryx-3ra1m2syg-fbopensource.vercel.app/shadcn/hooks/use-list-reorder.json