useSortable
hook is an abstraction that composes the useDroppable
and useDraggable
hooks.
useSortable
hook needs to be used within a descendant of a SortableContext
provider higher up in the tree.useDraggable
hook, the useSortable
hook should look very familiar, since, it is an abstraction on top of it.
In addition to the attributes
, listeners
,transform
and setNodeRef
arguments, which you should already be familiar with if you’ve used the useDraggable
hook before, you’ll notice that the useSortable
hook also provides a transition
argument.
listeners
property contains the activator event handlers for each Sensor that is defined on the parent DndContext
provider.
It should be attached to the node(s) that you wish to use as the activator to begin a sort event. In most cases, that will be the same node as the one passed to setNodeRef
, though not necessarily. For instance, when implementing a sortable element with a “drag handle”, the ref should be attached to the parent node that should be sortable, but the listeners can be attached to the handle node instead.
For additional details on the listeners
property, refer to the useDraggable
documentation.
useSortable
hook provides a set of sensible default attributes for draggable items. We recommend you attach these to your draggable elements, though nothing will break if you don’t.
For additional details on the attributes
property, refer to the useDraggable
documentation.
transform
property represents the displacement and change of scale transformation that a sortable item needs to apply to transition to its new position without needing to update the DOM order.
The transform
property for the useSortable
hook behaves similarly to the transform
property of the useDraggable
hook for the active sortable item, when there is no DragOverlay
being used.
useSortable
hook to function properly, it needs the setNodeRef
property to be attached to the HTML element you intend on turning into a sortable element:
ref
should be assigned to the outer container that you want to become draggable, but this doesn’t necessarily need to coincide with the container that the listeners are attached to:
useSortable
hook is simply an abstraction on top of the useDraggable
and useDroppable
hooks, in some advanced use cases, you may also use the setDroppableNodeRef
and setDraggableNodeRef
properties to connect them to different nodes. For example, if you want the draggable element to have a different dimension than the droppable element that will be sortable:
setActivatorNodeRef
It’s possible for the listeners to be attached to a different node than the one that setNodeRef
is attached to.
A common example of this is when implementing a drag handle and attaching the listeners to the drag handle:
setActivatorNodeRef
, focus will automatically be restored on the first focusable node of the draggable node registered via setNodeRef.
transition
argument documentation below.
id
argument is a string
or number
that should be unique.
Since the useSortable
is an abstraction on top of the useDroppable
and useDraggable
hooks, which both require a unique identifier, the useSortable
hook also requires a unique identifier.
The argument passed to the id
argument of useSortable
should match the id
passed in the items
array of the parent SortableContext
provider.
disabled
argument to true
.
transition
property for you. It conveniently disables transform transitions while not dragging, but ensures that items transition back to their final positions when the drag operation is ended or cancelled.
It also disables transitions for the active sortable element that is being dragged, unless there is a DragOverlay
being used.
The default transition is 250
milliseconds, with an easing function set to ease
, but you can customize this and pass any valid CSS transition timing function.
transition
style property to the same node that has the transform
property applied:
transform
and transition
properties:
transition
argument to null
:
SortableContext
provider.