useDraggableCollectionState

Manages state for a draggable collection.

install	`yarn add react-stately`
version	3.39.0
usage	`import {useDraggableCollectionState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useDraggableCollectionState(
  (props: DraggableCollectionStateOptions
)): DraggableCollectionState

Interface#

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`draggedKey`	`Key \| null`	The key of the item that initiated a drag.
`draggingKeys`	`Set<Key>`	The keys of the items that are currently being dragged.
`isDisabled`	`boolean`	Whether drag events are disabled.
`preview`	`RefObject<DragPreviewRenderer \| null>`	The ref of the element that will be rendered as the drag preview while dragging.
`getAllowedDropOperations`	`() => DropOperation[]`	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.
`getPreviewOffset`	`( (options: {previewRect: DOMRect, sourceRect: DOMRect, pointerPosition: {x: number, y: number }, defaultOffset: {x: number, y: number } } )) => {x: number, y: number }`	A function that returns the offset of the drag preview relative to the pointer. If not provided, a default offset is automatically calculated based on the click/touch position, falling back to the center of the preview in cases where the preview is smaller than the interaction point.

Methods

Method	Description
`isDragging( (key: Key )): boolean`	Returns whether the given key is currently being dragged.
`getKeysForDrag( (key: Key )): Set<Key>`	Returns the keys of the items that will be dragged with the given key (e.g. selected items).
`getItems( (key: Key )): DragItem[]`	Returns the items to drag for the given key.
`startDrag( (key: Key, , event: DragStartEvent )): void`	Begins a drag for the given key. This triggers the onDragStart event.
`moveDrag( (event: DragMoveEvent )): void`	Triggers an onDragMove event.
`endDrag( (event: DraggableCollectionEndEvent )): void`	Ends the current drag, and emits an onDragEnd event.

Example#

See the docs for useDraggableCollection in react-aria for an example of useDraggableCollectionState.

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`getItems`	`( (keys: Set<Key> )) => DragItem[]`	A function that returns the items being dragged.
`isDisabled`	`boolean`	Whether the drag events should be disabled.
`onDragStart`	`( (e: DraggableCollectionStartEvent )) => void`	Handler that is called when a drag operation is started.
`onDragMove`	`( (e: DraggableCollectionMoveEvent )) => void`	Handler that is called when the drag is moved.
`onDragEnd`	`( (e: DraggableCollectionEndEvent )) => void`	Handler that is called when the drag operation is ended, either as a result of a drop or a cancellation.
`preview`	`RefObject<DragPreviewRenderer \| null>`	The ref of the element that will be rendered as the drag preview while dragging.
`getAllowedDropOperations`	`() => DropOperation[]`	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.
`getPreviewOffset`	`( (options: {previewRect: DOMRect, sourceRect: DOMRect, pointerPosition: {x: number, y: number }, defaultOffset: {x: number, y: number } } )) => {x: number, y: number }`	A function that returns the offset of the drag preview relative to the pointer. If not provided, a default offset is automatically calculated based on the click/touch position, falling back to the center of the preview in cases where the preview is smaller than the interaction point.

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.
`UNSTABLE_filter( (filterFn: ( (nodeValue: string )) => boolean )): Collection<T>`	Filters the collection using the given function.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`index`	`number`	The index of this node within its parent.
`aria-label`	`string`	An accessibility label for this node.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`	The first selected key in the collection.
`lastSelectedKey`	`Key \| null`	The last selected key in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`collection`	`Collection<Node<unknown>>`	The collection of nodes that the selection manager handles.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.

Methods

Method	Description
`isSelected( (key: Key )): boolean`	Returns whether a key is selected.
`isSelectionEqual( (selection: Set<Key> )): boolean`	Returns whether the current selection is equal to the given selection.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`	Toggles, replaces, or extends selection to the given key depending on the pointer event and collection's selection mode.
`canSelectItem( (key: Key )): boolean`	Returns whether the given key can be selected.
`isDisabled( (key: Key )): boolean`	Returns whether the given key is non-interactive, i.e. both selection and actions are disabled.
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`isLink( (key: Key )): boolean`	Returns whether the given key is a hyperlink.
`getItemProps( (key: Key )): any`	Returns the props for the given item.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

string | number

'selection' | 'all'

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

'first' | 'last'

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`type`	`'dragstart'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`type`	`'dragmove'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`isInternal`	`boolean`	Whether the drop ended within the same collection as it originated.
`type`	`'dragend'`	The event type.
`dropOperation`	`DropOperation`	The drop operation that occurred.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

'copy'
  | 'link'
  | 'move'
  | 'cancel'

Name	Type	Description
`type`	`string`

(
  (items: DragItem[],
  , callback: (
    (node: HTMLElement
      |  | null
  )) => void
)) => void

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`draggedKey`	`Key \| null`	The key of the item that initiated a drag.
`draggingKeys`	`Set<Key>`	The keys of the items that are currently being dragged.
`isDisabled`	`boolean`	Whether drag events are disabled.
`preview`	`RefObject<DragPreviewRenderer \| null>`	The ref of the element that will be rendered as the drag preview while dragging.
`getAllowedDropOperations`	`() => DropOperation[]`	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.
`getPreviewOffset`	`( (options: {previewRect: DOMRect, sourceRect: DOMRect, pointerPosition: {x: number, y: number }, defaultOffset: {x: number, y: number } } )) => {x: number, y: number }`	A function that returns the offset of the drag preview relative to the pointer. If not provided, a default offset is automatically calculated based on the click/touch position, falling back to the center of the preview in cases where the preview is smaller than the interaction point.

Methods

Method	Description
`isDragging( (key: Key )): boolean`	Returns whether the given key is currently being dragged.
`getKeysForDrag( (key: Key )): Set<Key>`	Returns the keys of the items that will be dragged with the given key (e.g. selected items).
`getItems( (key: Key )): DragItem[]`	Returns the items to drag for the given key.
`startDrag( (key: Key, , event: DragStartEvent )): void`	Begins a drag for the given key. This triggers the onDragStart event.
`moveDrag( (event: DragMoveEvent )): void`	Triggers an onDragMove event.
`endDrag( (event: DraggableCollectionEndEvent )): void`	Ends the current drag, and emits an onDragEnd event.