Installation
CLI
Manual
Install the following dependencies:
Copy the composition utilities into your lib/composition.ts
file.
Copy and paste the following code into your project.
Layout
Import the parts, and compose them together.
Examples
With Dynamic Overlay
Display a dynamic overlay when an item is being dragged.
With Handle
Use ItemHandle
as a drag handle for sortable items.
Trick | Difficulty | Points | |
---|---|---|---|
The 900 | Expert | 9000 | |
Indy Backflip | Advanced | 4000 | |
Pizza Guy | Intermediate | 1500 | |
360 Varial McTwist | Expert | 5000 |
With Primitive Values
Use an array of primitives (string or number) instead of objects for sorting.
API Reference
Root
The main container component for sortable functionality.
Prop | Type | Default |
---|---|---|
value | TData[] | - |
onValueChange | (items: TData[]) => void | - |
getItemValue | (item: TData) => UniqueIdentifier | - |
onMove | (event: DragEndEvent & { activeIndex: number; overIndex: number; }) => void | - |
modifiers | Modifiers | Automatically selected based on orientation:
- vertical: [restrictToVerticalAxis, restrictToParentElement]
- horizontal: [restrictToHorizontalAxis, restrictToParentElement]
- mixed: [restrictToParentElement] |
strategy | SortingStrategy | Automatically selected based on orientation:
- vertical: verticalListSortingStrategy
- horizontal: horizontalListSortingStrategy
- mixed: undefined |
sensors | SensorDescriptor<any>[] | [
useSensor(MouseSensor),
useSensor(TouchSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
}),
] |
orientation | "vertical" | "horizontal" | "mixed" | "vertical" |
id | string | React.useId() |
accessibility | { announcements?: Announcements | undefined; container?: Element | undefined; restoreFocus?: boolean | undefined; screenReaderInstructions?: ScreenReaderInstructions | undefined; } | - |
autoScroll | boolean | Options | false |
cancelDrop | CancelDrop | - |
children | ReactNode | - |
collisionDetection | CollisionDetection | Based on orientation:
- vertical: closestCenter
- horizontal: closestCenter
- mixed: closestCorners |
measuring | MeasuringConfiguration | - |
onDragStart | (event: DragStartEvent) => void | - |
onDragMove | (event: DragMoveEvent) => void | - |
onDragOver | (event: DragOverEvent) => void | - |
onDragEnd | (event: DragEndEvent) => void | - |
onDragCancel | (event: DragCancelEvent) => void | - |
flatCursor | boolean | false |
onDragAbort | (event: DragAbortEvent) => void | - |
onDragPending | (event: DragPendingEvent) => void | - |
Content
Container for sortable items. Multiple SortableContent
components can be used within a Sortable
component.
Prop | Type | Default |
---|---|---|
strategy | SortingStrategy | Automatically selected based on orientation:
- vertical: verticalListSortingStrategy
- horizontal: horizontalListSortingStrategy
- mixed: undefined |
children | ReactNode | - |
asChild | boolean | false |
Item
Individual sortable item component.
Prop | Type | Default |
---|---|---|
value | UniqueIdentifier | - |
asHandle | boolean | false |
asChild | boolean | false |
disabled | boolean | false |
Data Attribute | Value |
---|---|
[data-dragging] | Present when the item is being dragged. |
[data-sortable-item] | Present on all sortable items. |
ItemHandle
A button component that acts as a drag handle for sortable items.
Prop | Type | Default |
---|---|---|
asChild | boolean | false |
Data Attribute | Value |
---|---|
[data-dragging] | Present when the parent sortable item is being dragged. |
The component extends the base Button
component and adds the following styles:
select-none
for pointer eventscursor-grab
when not dragging (unlessflatCursor
is true)cursor-grabbing
when dragging (unlessflatCursor
is true)cursor-default
whenflatCursor
is true
Overlay
The overlay component that appears when an item is being dragged.
Prop | Type | Default |
---|---|---|
container | HTMLElement | DocumentFragment | document.body |
dropAnimation | DropAnimation | { sideEffects: defaultDropAnimationSideEffects({ styles: { active: { opacity: "0.4" } } }), } |
children | string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | ((params: { ...; }) => ReactNode) | - |
adjustScale | boolean | - |
transition | string | TransitionGetter | - |
modifiers | Modifiers | - |
wrapperElement | string | number | symbol | - |
zIndex | number | - |
Accessibility
Keyboard Interactions
Key | Description |
---|---|
EnterSpace | Picks up the sortable item for reordering when released, and drops the item in its new position when pressed again. |
ArrowUp | Moves the sortable item up in vertical orientation. |
ArrowDown | Moves the sortable item down in vertical orientation. |
ArrowLeft | Moves the sortable item left in horizontal orientation. |
ArrowRight | Moves the sortable item right in horizontal orientation. |
Esc | Cancels the sort operation and returns the item to its original position. |