useOrderList

A headless hook that manages list ordering with selection-based controls and optional drag-and-drop support.

New York

Rome

London

Istanbul

Paris

basic-demo

Usage#

import { useOrderList } from '@primereact/headless/orderlist';
 
const orderList = useOrderList({
    value: items,
    selection,
    draggable: true,
    onReorder: (e) => setItems(e.value)
});
 
return (
    <div {...orderList.rootProps}>
        <div {...orderList.controlsProps}>
            <button {...orderList.firstProps}>Top</button>
            <button {...orderList.prevProps}>Up</button>
            <button {...orderList.nextProps}>Down</button>
            <button {...orderList.lastProps}>Bottom</button>
        </div>
        <div {...orderList.listProps}>
            {orderList.state.value.map((item, i) => (
                <div key={i} {...orderList.getOptionProps(item, i)}>
                    {item.name}
                </div>
            ))}
        </div>
    </div>
);

useOrderList manages item ordering with move operations and drag-and-drop. Pair it with Listbox for built-in selection and keyboard navigation.

Features#

Returns spread-ready prop objects (rootProps, listProps, controlsProps, prevProps, nextProps, firstProps, lastProps)
Selection-based move operations: moveUp, moveDown, moveTop, moveBottom
Built-in drag-and-drop with draggable prop
Clone or empty placeholder modes during drag
Per-option props via getOptionProps

Behavior#

Basic Ordering#

Pass value and onReorder to manage the list. Use moveUp, moveDown, moveTop, moveBottom with selection to reorder items.

const [items, setItems] = React.useState(['A', 'B', 'C']);
const [selection, setSelection] = React.useState([]);
 
const orderList = useOrderList({
    value: items,
    selection,
    onReorder: (e) => setItems(e.value)
});

Drag and Drop#

Set draggable to enable drag-and-drop reordering.

const orderList = useOrderList({
    value: items,
    draggable: true,
    onReorder: (e) => setItems(e.value)
});

Placeholder#

Set placeholder to "clone" to show a visual copy of the dragged item in its original position. Default is "empty" which preserves height only.

const orderList = useOrderList({
    value: items,
    draggable: true,
    placeholder: 'clone',
    onReorder: (e) => setItems(e.value)
});

Style the placeholder with [data-sortable-placeholder] attribute.

Disabled#

Set disabled to prevent all interactions.

const orderList = useOrderList({ value: items, disabled: true });

Custom Styling with Data Attributes#

Every prop object includes data-scope and data-part attributes for CSS targeting.

[data-scope='orderlist'][data-part='root'] {
    display: flex;
    gap: 1rem;
}
 
[data-scope='orderlist'][data-part='list'] {
    min-height: 200px;
}
 
[data-sortable-placeholder] {
    opacity: 0.4;
}

Option Attributes#

Attribute	Value
`data-selected`	Present when the item is selected
`data-sortable-item`	Present on every sortable item
`data-sortable-container`	Container id for the sortable group
`data-dragging`	Present on the item being dragged
`data-dropping`	Present briefly during the drop animation
`data-sortable-placeholder`	Present on the placeholder clone left behind during drag