useSortable
hook is an abstraction that composes the useDroppable
and useDraggable
hooks.
To function properly, the
useSortable
hook needs to be used within a descendant of a SortableContext
provider higher up in the tree.Usage
If you’re already familiar with theuseDraggable
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.
Properties
Listeners
Thelisteners
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.
Attributes
TheuseSortable
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
Thetransform
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.
Node ref
In order for theuseSortable
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:
Activator
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:
Focus management is automatically handled by @dnd-kit. When the activator event is a Keyboard event, focus will automatically be restored back to the first focusable node of the activator node.If no activator node is set via
setActivatorNodeRef
, focus will automatically be restored on the first focusable node of the draggable node registered via setNodeRef.
Transition
Refer to thetransition
argument documentation below.
Arguments
Identifier
Theid
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
If you’d like to temporarily disable a sortable item from being interactive, set thedisabled
argument to true
.
Transition
The transition argument controls the value of thetransition
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
:
Sorting strategy
Optionally, you can pass a local sorting strategy that differs from the global sorting strategy passed to the parentSortableContext
provider.