InputsReact
A list the user puts in order.
Rendered by React 19.3.1
Loading React…Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<SortableList.Root>
<SortableList.List>
<SortableList.Item>
<SortableList.Handle />
</SortableList.Item>
</SortableList.List>
</SortableList.Root>
// Not in this example: SortableList.MoveButtonExamples
Item Drag
A playlist with dragActivator="item": the whole row drags with the mouse, a touch after a hold; the Handle stays for keys.
Horizontal
Four stages in a row with orientation="horizontal", moved with the left and right arrows.
Grid
Six shortcuts in a three column grid, a place with the left and right arrows and a row with the up and down.
Move Buttons
Drinks with MoveButtons and no Handle: nothing drags, each button moves its item and is announced.
Locked
Sections with canMove: the cover and the appendix stay where they are and the others skip their places.
Controlled
The order held by the app, with Handles and MoveButtons, a Reset from outside and the last move from the event details.
Form
A ranking in a Field and Form, submitted as priorities in the shown order and brought back by a reset.
API reference
24 props across 5 parts, in React syntax. className, style, render are listed once, under Shared props.
HandleSortableList.Handle
The button that picks its Item up: Space or Enter, a click, or a pointer drag. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
focusableWhenDisabledWhether the Handle stays focusable while it cannot move its Item. | boolean | true |
| Data attribute | Description |
|---|---|
data-grabbed | Present when the item is held by a key press or a click on the handle. |
data-dragging | Present when the item is the one being moved, by pointer or keyboard. |
data-disabled | Present when the item or the sortable list is disabled. |
ItemSortableList.Item
One entry of the list, for one item of the value. Renders a <li>.
| Prop | Type | Default |
|---|---|---|
valuerequiredThe item this entry shows: an entry of the Root's value. | any | — |
disabledWhether the item cannot be moved. | boolean | false |
| Data attribute | Description |
|---|---|
data-index | The item's index in the committed value. |
data-disabled | Present when the item or the sortable list is disabled. |
data-dragging | Present when the item is the one being moved, by pointer or keyboard. |
data-grabbed | Present when the item is held by a key press or a click on its handle. |
ListSortableList.List
The list of items, in the value's order. Renders an <ol>.
| Prop | Type | Default |
|---|---|---|
childrenThe Items, or a function that renders one for each item of the value, in order. | React.ReactNode | ((item: any, index: number) => React.ReactNode) | — |
| Data attribute | Description |
|---|---|
data-orientation | The layout the items are ordered in. |
data-disabled | Present when the sortable list is disabled. |
data-empty | Present when the list has no items. |
data-sorting | Present while an item is grabbed or dragged past the drag threshold. |
MoveButtonSortableList.MoveButton
A button that moves its Item one place, or to the start or the end. While the move does not apply it is aria-disabled and keeps focus. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
torequiredWhere the button moves its Item: one place back or forward, or to the start or the end. | SortableListMoveTarget | — |
focusableWhenDisabledWhether the button stays focusable while its move does not apply. | boolean | true |
| Data attribute | Description |
|---|---|
data-to | Where the button moves the item. |
data-disabled | Present when the move does not apply: the item is at that end, the item or the sortable list is disabled, or canMove refuses every target in that direction. |
RootSortableList.Root
Groups a sortable list and owns its value: every item, in order. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
valueEvery item, in order. | readonly Item[] | — |
defaultValueEvery item, in order, when the component is initially rendered, and what a form reset | readonly Item[] | [] |
onValueChangeEvent handler called once per committed move. | ((value: Item[], eventDetails: SortableListRoot.ChangeEventDetails<Item>) => void) | — |
isItemEqualToValueCustom comparison logic used to tell two items apart. | ((item: Item, other: Item) => boolean) | — |
itemToStringLabelConverts an item to the text its Handle and MoveButtons are named and announced with. | ((item: Item) => string) | — |
itemToStringValueConverts an item to the string submitted with a form. | ((item: Item) => string) | — |
canMoveWhether an item may be moved to a place. | ((details: SortableListCanMoveDetails<Item>) => boolean) | — |
orientationThe layout the keys and the drag follow: a column, a row, or a wrapping grid. | SortableListOrientation | 'vertical' |
dragActivatorWhat a pointer drag starts from: the Handle only, or anywhere on an Item but its controls. | SortableListDragActivator | 'handle' |
longPressDelayHow long, in milliseconds, a touch on an Item's body is held before it drags. | number | 250 |
disabledWhether the component should ignore user interaction. | boolean | false |
readOnlyWhether the user should be unable to move items. | boolean | false |
nameIdentifies the field when a form is submitted: one entry per item, in order. | string | — |
formIdentifies the form that owns the hidden inputs. | string | — |
labelsThe texts of the names, the instructions and the announcements. | Partial<SortableListLabels> | — |
actionsRefA ref to imperative actions. | React.Ref<SortableListRoot.Actions<Item>> | — |
| Data attribute | Description |
|---|---|
data-orientation | The layout the items are ordered in. |
data-disabled | Present when the sortable list is disabled. |
data-readonly | Present when the sortable list does not allow changing the order. |
data-empty | Present when the list has no items. |
data-sorting | Present while an item is grabbed or dragged past the drag threshold. |
data-valid | Present when the sortable list is in a valid state (when wrapped in Field.Root). |
data-invalid | Present when the sortable list is in an invalid state (when wrapped in Field.Root). |
data-touched | Present when the sortable list has been touched (when wrapped in Field.Root). |
data-dirty | Present when the sortable list's order has changed (when wrapped in Field.Root). |
data-filled | Present when the list has items (when wrapped in Field.Root). |
data-focused | Present when an element inside the sortable list is focused (when wrapped in Field.Root). |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| SpaceEnter | Picks the item up; again, drops it where it is | Handle |
| ArrowUpArrowDown | While picked up, moves the item one place (a row in a grid); ArrowLeft and ArrowRight in a row, swapped in a right-to-left page | Handle |
| HomeEnd | While picked up, moves the item to the first or last place that is allowed | Handle |
| AltArrowUpAltArrowDown | With nothing picked up, moves the item one place earlier or later at once; focus stays | Handle |
| Escape | While picked up, puts the item back and says so; a surrounding Dialog stays open | Handle |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | a role="status" region, polite and atomic, and a hidden description of the keys | each pick up, step, drop, cancel and move is said once |
| List | role="list", named by the Field label, aria-labelledby or aria-label | the list is said with its name and its count |
| Item | role="listitem", no tabindex; data-index is its place | the list reports its items and their count, and the page has one tab stop per Handle |
| Handle | a button named "Reorder {name}", aria-pressed while picked up, aria-describedby the instructions, aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown" | the button says what it moves, whether it holds it and which keys move it |
| Handle | aria-disabled, not disabled, when the item cannot move | a locked item's handle keeps focus and the reader says why nothing happens |
| MoveButton | a button named "Move {name} up", "down", "left", "right", "to start" or "to end"; aria-disabled where the move does not apply | the button path says where the item goes, and focus stays on it after a press |
Focus order
- Every
HandleandMoveButtonis a tab stop, in DOM order; there is no roving focus and anItemtakes none. - Picking up, stepping and dropping keep focus on the
Handle. After a move theHandleof the moved item has focus in its new place. - Tab, or a click outside the
List, cancels a pick up. Nothing takes focus on mount or on a form reset.