Reorder

When to Use

Use Reorder when a person decides and saves the order of items in one list. Do not use it for automatic sorting by name, date, or status. Tables, trees, Kanban boards, and movement between containers need component-specific APIs that may reuse DragDrop internally.

Features

The behavior Atom owns before your product adds appearance.

• Controlled stable-identity order.
• Native ordered-list and list-item defaults.
• Mouse, pen, delayed-touch, and keyboard reordering.
• Direct move before, after, to start, and to end controls.
• Localizable instructions and live announcements.
• Disabled, read-only, per-item disabled, vertical, horizontal, and RTL modes.
• Drop-position state for styled layers without Atom-owned visuals.

Import

import { Reorder } from "@flowstack-ui/atom";

Anatomy

<Reorder.Root>
  <Reorder.Item>
    <Reorder.Handle />
    <Reorder.MoveBefore />
    <Reorder.MoveAfter />
    <Reorder.MoveToStart />
    <Reorder.MoveToEnd />
    <Reorder.DropIndicator />
  </Reorder.Item>
</Reorder.Root>

API Reference

Root

Owns the controlled identity order and renders an ol by default.

onItemsChange details include activeValue, overValue, position, previousIndex, nextIndex, and input (keyboard, pointer, or control).

Item

Registers one stable identity and renders an li by default.

Handle

Native button that starts and controls dragging. It must receive an accessible name such as Move Verify production.

MoveBefore

Native button that immediately moves the Item one logical position earlier. It disables at the first boundary.

MoveAfter

Native button that immediately moves the Item one logical position later. It disables at the last boundary.

MoveToStart

Native button that immediately moves the Item to the first position.

MoveToEnd

Native button that immediately moves the Item to the last position.

All movement buttons accept native button props, asChild, render, and consumer content. They emit [data-slot] and [data-move], and require an authored accessible name.

DropIndicator

Decorative span that exposes the proposed insertion position.

Examples

import { useState } from "react";
import { Reorder } from "@flowstack-ui/atom";

const labels: Record<string, string> = {
  verify: "Verify production",
  approve: "Request approval",
  deploy: "Deploy release",
};

export function ReorderExample() {
  const [items, setItems] = useState(["verify", "approve", "deploy"]);

  return (
    <Reorder.Root
      items={items}
      getItemLabel={(value) => labels[value] ?? value}
      onItemsChange={(nextItems) => setItems(nextItems)}
    >
      {items.map((value) => (
        <Reorder.Item key={value} value={value}>
          <Reorder.Handle aria-label={`Move ${labels[value]}`}>
            Move
          </Reorder.Handle>
          <span>{labels[value]}</span>
          <Reorder.MoveBefore aria-label={`Move ${labels[value]} up`}>Up</Reorder.MoveBefore>
          <Reorder.MoveAfter aria-label={`Move ${labels[value]} down`}>Down</Reorder.MoveAfter>
          <Reorder.DropIndicator />
        </Reorder.Item>
      ))}
    </Reorder.Root>
  );
}

Accessibility

Root and Item use native ordered-list semantics. Handles and movement operations are native buttons. The handle receives generated instructions and Root announces movement with human labels and one-based positions. Keep movement buttons visibly available: they are the simple-pointer alternative required by WCAG 2.2 Dragging Movements.

Use stable record IDs as value, render Items in the exact order supplied to Root, and preserve those keys after updates so focus remains on the moved control. Applications own persistence, Undo, failures, and conflicts.

Changelog

Unreleased

• No unreleased changes.

0.23.0

• Added the initial controlled linear reorder preset with drag, keyboard, direct movement controls, announcements, direction support, and drop state.