useSortable
The 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 the 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.
Properties
Listeners
The 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.
Attributes
The 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
The 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.
Node ref
In order for the 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:
Keep in mind that the 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:
Since the 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:
When the activator node differs from the draggable node, we recommend setting the activator node ref on the activator node:
This helps @dnd-kit more accurately handle automatic focus management and can also be accessed by sensors for enhanced activation constraints.
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 the transition
argument documentation below.
Arguments
Identifier
The 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
If you'd like to temporarily disable a sortable item from being interactive, set the disabled
argument to true
.
Transition
The transition argument controls the value of the 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.
Make sure you pass the transition
style property to the same node that has the transform
property applied:
If you prefer, you may also use CSS variables to manage the transform
and transition
properties:
To disable transitions entirely, set the transition
argument to null
:
If you prefer to manage transitions yourself, you may also choose to do so, but this isn't something we recommend.
Sorting strategy
Optionally, you can pass a local sorting strategy that differs from the global sorting strategy passed to the parent SortableContext
provider.
Last updated