useSortable Hook - React

Usage

The useSortable hook requires an id and an index. It accepts all the same options as the Sortable class. Refer to the Input section below for more information.

API Reference

The useSortable hook is a thin wrapper around the Sortable class that makes it easier to create sortable elements in React. It therefore accepts all of the same input arguments.

Input

The useSortable hook accepts all of the same arguments as the useDraggable hook and useDroppable hooks, as well as additional arguments that are specific to sortable elements.

string | number

required

The identifier of the sortable element. Should be unique within the same drag and drop context provider.

index

number

required

The index of the sortable element. This is used to determine the position of the element in the list.

transition

{duration?: number; easing?: string: idle: boolean} | null

Optionally supply a transition to animate the sortable element when it is being sorted.

child attributes

duration

number

The duration of the transition in milliseconds.

easing

string

The easing function to use for the transition.

idle

boolean

Whether the sortable item should transition to its new position when its index changes, but there is no drag operation in progress.

element

Element | Ref<Element>

If you already have a reference to the element, you can pass it to the element option instead of using the ref that is returned by the useSortable hook to connect the sortable element.

handle

Element | Ref<Element>

If you already have a reference to the drag handle element, you can pass it to the handle option instead of using the handleRef that is returned by the useSortable hook to connect the sortable handle element.

modifiers

Modifier[]

An array of modifiers that can be used to modify or restrict the behavior of the sortable element.

sensors

Sensors[]

An array of sensors that can be bound to the sortable element to detect drag interactions.

target

Element | Ref<Element>

If you already have a reference to the element you want to use as the droppable target for this sortable element, you can pass it to the target option instead of using the targetRef that is returned by the useSortable hook.

Type | Type[] | ((source: Draggable) => boolean)

Restrict which draggables can be dropped on this sortable item. Pass a single type, an array of types, or a predicate that receives the draggable and returns true to accept it. If omitted, every draggable is accepted.

type

string | number | Symbol

An identifier used by other sortables’ or droppables’ accept rules to decide whether this item can be a drop target for a given draggable.

group

string | number | Symbol

An optional identifier for grouping sortable items. Items with the same group can be sorted within the same list — useful for multi-list sortable layouts. Items without a group are treated as belonging to the same implicit group.

collisionDetector

(input: CollisionDetectorInput) => Collision | null

Optionally supply a collision detector function can be used to detect collisions between the droppable element and draggable elements.

collisionPriority

number

Optionally supply a number to set the collision priority of the droppable target of this sortable element. The higher the number, the higher the priority when detecting collisions. This can be useful if there are multiple droppable elements that overlap.

disabled

boolean

Set to true to prevent the sortable element from being sortable.

plugins

PluginDescriptor[]

An array of plugin descriptors for per-entity plugin configuration. Use Plugin.configure() to create descriptors. For example, Feedback.configure({ feedback: 'clone' }).

data

{[key: string]: any}

The data argument is for advanced use-cases where you may need access to additional data about the sortable element in event handlers, modifiers, sensors or custom plugins.

effects

() => Effect[]

This is an advanced feature and should not need to be used by most consumers.

You can supply a function that returns an array of reactive effects that can be set up and automatically cleaned up when the component invoking the useSortable hook element is unmounted.

Output

The useSortable hook returns an object containing the following properties:

ref

Ref<Element>

A React ref that can be assigned to the element you want to connect as the draggable element and droppable target for this sortable instance.

targetRef

Ref<Element>

A React ref that can be assigned to the element you want to use as the droppable target for this sortable element.

sourceRef

Ref<Element>

A React ref that can be assigned to the element you want to use as the draggable source element for this sortable element.

handleRef

Ref<Element>

A React ref that can be assigned to the element you want to use as the drag handle element for this sortable element.

isDropTarget

boolean

A boolean value that indicates whether the sortable element is currently a drop target.

isDragSource

boolean

A boolean value that indicates whether the sortable is the source of the drag operation that is in progress.

isDragging

boolean

A boolean value that indicates whether the sortable is currently being dragged.

isDropping

boolean

A boolean value that indicates whether the sortable is being dropped. This can be used to style the sortable element differently during the drop animation.