useDroppableCollectionState

Manages state for a droppable collection.

install	`yarn add react-stately`
version	3.33.0
usage	`import {useDroppableCollectionState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useDroppableCollectionState(
  (props: DroppableCollectionStateOptions
)): DroppableCollectionState

Interface#

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`target`	`DropTarget \| null`	The current drop target.
`isDisabled`	`boolean`	Whether drop events are disabled.

Methods

Method	Description
`setTarget( (target: DropTarget \| \| null )): void`	Sets the current drop target.
`isDropTarget( (target: DropTarget )): boolean`	Returns whether the given target is equivalent to the current drop target.
`getDropOperation( (e: DropOperationEvent )): DropOperation`	Returns the drop operation for the given parameters.

Example#

See the docs for useDroppableCollection in react-aria for an example of useDroppableCollectionState.

Name	Type	Default	Description
`collection`	`Collection<Node<unknown>>`	—	A collection of items.
`selectionManager`	`MultipleSelectionManager`	—	An interface for reading and updating multiple selection state.
`isDisabled`	`boolean`	—	Whether the drop events should be disabled.
`acceptedDragTypes`	`'all' \| Array<string \| symbol>`	`'all'`	The drag types that the droppable collection accepts. If the collection accepts directories, include `DIRECTORY_DRAG_TYPE` in your array of allowed types.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler that is called when external items are dropped "between" items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler that is called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler that is called when items are dropped "on" an item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler that is called when items are reordered via drag in the source collection.
`shouldAcceptItemDrop`	`( (target: ItemDropTarget, , types: DragTypes )) => boolean`	—	A function returning whether a given target in the droppable collection is a valid "on" drop target for the current drag types.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters a drop target.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits a drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on a drop target. When defined, this overrides other drop handlers such as `onInsert`, and `onItemDrop`.
`getDropOperation`	`( target: DropTarget, types: DragTypes, allowedOperations: DropOperation[] ) => DropOperation`	—	A function returning the drop operation to be performed when items matching the given types are dropped on the drop target.

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.

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.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`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.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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
`items`	`DropItem[]`	The dropped items.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`target`	`ItemDropTarget`	The drop target.

TextDropItem
  | FileDropItem
  | DirectoryDropItem

Properties

Name	Type	Description
`kind`	`'text'`	The item kind.
`types`	`Set<string>`	The drag types available for this item. These are often mime types, but may be custom app-specific types.

Methods

Method	Description
`getText( (type: string )): Promise<string>`	Returns the data for the given type as a string.

Properties

Name	Type	Description
`kind`	`'file'`	The item kind.
`type`	`string`	The file type (usually a mime type).
`name`	`string`	The file name.

Methods

Method	Description
`getFile(): Promise<File>`	Returns the contents of the file as a blob.
`getText(): Promise<string>`	Returns the contents of the file as a string.

Properties

Name	Type	Description
`kind`	`'directory'`	The item kind.
`name`	`string`	The directory name.

Methods

Method	Description
`getEntries(): AsyncIterable<FileDropItem \| DirectoryDropItem>`	Returns the entries contained within the directory.

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

Name	Type	Description
`type`	`'item'`	The drop target type.
`key`	`Key`	The item key.
`dropPosition`	`DropPosition`	The drop position relative to the item.

'on'
  | 'before'
  | 'after'

Name	Type	Description
`items`	`DropItem[]`	The dropped items.
`dropOperation`	`DropOperation`	The drop operation that should occur.

Name	Type	Description
`items`	`DropItem[]`	The dropped items.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`isInternal`	`boolean`	Whether the drag originated within the same collection as the drop.
`target`	`ItemDropTarget`	The drop target.

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were reordered.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`target`	`ItemDropTarget`	The drop target.

Method	Description
`has( (type: string \| \| symbol )): boolean`	Returns whether the drag contains data of the given type.

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'dropenter'`	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.

RootDropTarget | ItemDropTarget

Name	Type	Description
`type`	`'root'`	The event type.

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'dropexit'`	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
`target`	`DropTarget`	The drop target.
`type`	`'drop'`	The event type.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`items`	`DropItem[]`	The dropped items.
`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.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`target`	`DropTarget \| null`	The current drop target.
`isDisabled`	`boolean`	Whether drop events are disabled.

Methods

Method	Description
`setTarget( (target: DropTarget \| \| null )): void`	Sets the current drop target.
`isDropTarget( (target: DropTarget )): boolean`	Returns whether the given target is equivalent to the current drop target.
`getDropOperation( (e: DropOperationEvent )): DropOperation`	Returns the drop operation for the given parameters.