@gridui/sortable

Core family. Public API: Sortable, SortableAnnouncement, SortableEntry, SortableHandle, SortableHandleProps, SortableItem, SortableItemProps, SortableMessages, SortableMoveButton, SortableMoveButtonProps, SortableProps.

Import components from @gridui/sortable and load @gridui/sortable/styles.css after Theme. Load styles for any composed dependency used by this family. Applications own routes, labels, state persistence, and branding.

See component ownership and release history.

Sortable collections

Sortable, SortableItem, and SortableHandle wrap the current @dnd-kit/react API. Sortable owns pointer, touch, and keyboard interaction, drag feedback, focus restoration, and localized accessibility announcements. Consumers own the ordered records and commit changes through onMove(sourceIndex, targetIndex).

Pass items with stable, unique string or numeric IDs and human-readable labels. Supply localized messages.instructions, messages.roleDescription, and an announce function for the start, move, end, and cancel phases. Announcements receive the item label, one-based position, and collection count. Internal IDs are never used as spoken labels.

Each SortableItem receives its ID and zero-based index. It renders a div by default; render={<li />} preserves an ordered list. Native props and refs are merged through Radix Slot (or passed to a render callback). Place SortableHandle inside each item with a localized label. In a filled grid, keep GridItem as the direct React child and use GridItem asChild around SortableItem. No extra DOM wrapper is added, so list semantics, direct grid children, and framed seams remain intact. The handle is a themed 2.75rem button. Only the handle suppresses touch scrolling; the remaining content keeps normal scrolling and independent actions. Items expose data-sort-state="idle|dragging|dropping" for feedback and readiness checks. Their default border-box sizing keeps padded drag shapes and keyboard targets aligned even when the consumer does not load a global CSS reset.

Space or Enter picks up and drops an item; arrow keys move through a list or responsive grid; Escape cancels. Pointer and touch use the same dedicated handle. Canceled, disabled, unchanged, or stale operations do not call onMove. Collections with fewer than two items disable sorting. Reordering and drop transitions respect reduced motion. FilePicker retains native external file dropping; collection sorting does not replace file import.

The UI browser fixture verifies pointer, touch, keyboard, cancellation, focus, announcements, disabled states, independent contexts, and responsive grid cells.

Individual disabled or loading handles, including native fieldset disabling, do not start or commit sorting. Disabling the source handle during an operation cancels it. Custom handle classes merge with the default interaction styles.

Move buttons

Place SortableMoveButton inside a SortableItem to move the item one position with a click, tap, or key press. Set direction="previous" or direction="next" and provide an item-specific localized label. The default arrows suit vertical lists. Pass decorative children for other orientations.

The buttons call the same onMove as dragging and announce the new position through messages.announce with phase "end". At either boundary the unavailable button uses aria-disabled so a move to that boundary can retain focus.

Component reference contains focused API pages for each public component.