alpha

Drag and Drop

This page describes how to enable drag and drop functionality for the various React Spectrum components that support it.

Introduction#

Drag and drop is a common UI interaction that allows users to transfer data between two locations by directly moving a visual representation on screen. It is a flexible, efficient, and intuitive way for users to perform a variety of tasks, and is widely supported across both desktop and mobile operating systems. In addition to the standard mouse and touch interactions, React Spectrum also implements keyboard and screen reader accessible alternatives for drag and drop to enable all users to perform these tasks.

Drag and Drop Concepts#

Before we dive into how to enable drag and drop in React Spectrum, let's touch briefly on the terminology and concepts of drag and drop. In a drag and drop operation, there is a drag source and a drop target. The drag source is the starting location of your dragged data and the drop target is its intended destination. The dragged data is made up of one or more drag items, each of which contains information specific to their original item within the drag source.

A drag item contains several pieces of information: the type of the data, the item's kind, and the actual data itself. The type of a drag item can be one of the common mime types or a custom type specific to your application. Multiple types can be attached to a single drag item so that the item's data can be provided in different formats for interoperability with various drop targets. For example, an image could be represented by an image/jpeg type and thus be recognized as a JPEG by a file upload drop target but also have a plain/text type that allows the image's file name to be communicated to a text input drop target. In addition, there are two kinds of items: string items include inline data in the form of a Unicode string, and file items include a reference to a file from the user's computer.

There are several drop operations that can be performed in a drag and drop operation: "move", "copy", "link", and "cancel". A "move" operation indicates that the dragged data will be moved from its source location to the target location. A "copy" operation indicates that the dragged data will be copied to the target destination. A "link" operation indicates that there will be a relationship established between the source and target locations. Finally, a "cancel" operation indicates that the drag and drop operation will be canceled, resulting in no changes made to the source or target. The drag source can specify what drop operations are allowed for its data, allowing the drop source to decide what operation to perform on drop by using the restrictions set by the drag source as a guideline.

Collection components, such as ListView, support multiple drop positions. The component may support a "root" drop position, allowing items to be dropped on the collection as a whole. It may also support "on" drop positions, such as when dropping into a folder in a list. If the collection allows reordering of its items, it could support "between" drop positions, allowing the user to insert or move items between other items. Any number of these drop positions can be allowed at the same time and the component can use the types of the dragged items to selectively allow or disallow certain positions.

Interaction modes#

There are several interaction modes that need to be considered for drag and drop. When using a mouse, you can click an item and drag by holding the mouse button down and moving the pointer. A drop can be performed by releasing the mouse button or canceled by the Esc key. A similar interaction can be performed via touch, with a drag initiated via a long press and a drop performed by removing your finger from the screen. In both cases, selecting and dragging an item is often accompanied by a drag preview. The drag preview is a smaller version of the dragged item that follows the cursor or touch point. When multiple items are dragged at once, the drag preview displays a stack of items instead, accompanied by a badge reflecting the total number of dragged items. Drop targets are visually highlighted when dragged over, and the desired drop operation can be controlled via modifier key presses or drop activations via hovering over the drop target for a period of time.

For keyboards, copy and paste shortcuts have traditionally been the alternative method to drag and drop. This comes with many limitations as it is often hard to know where pasting is allowed and difficult to control the exact positioning of the pasted items. Touch screen readers are even more limited in their ability to perform these operations since they often lack access to a keyboard and thus cannot copy paste in the same manner.

React Spectrum attempts to resolve the above limitations by providing interactive drag affordances that bring a user into drag and drop mode when triggered via keyboard or screen reader virtual click. To perform a drag and drop operation via a keyboard, first select the items to be dragged by focusing the row and pressing Space. You can then start the drag operation by moving focus to the drag handle on any of the selected rows via the arrow keys and hitting Enter or Space. Once a drag operation is started, you will be automatically brought to the first valid drop target. Tab can then be used to cycle through other valid drop targets. For collection components like the ListView above, Tab will move you on or off the overall component itself whereas ArrowUp and ArrowDown will cycle through the valid drop targets within the component itself. Hitting Enter will then confirm the drop operation on the focused drop target. To cancel a drag operation, you can hit Esc at any time.

For screen readers, please follow the custom instructions announced when focusing the row's drag handle to begin a drag operation. For screen readers on mobile devices, swiping left and right will move you between valid drop targets and double tapping will confirm a drop operation. Go ahead and try out drag and drop in the example below!

Example#

Creating the draggable list#

For the first ListView in the example above, we want to make the rows draggable and have the dragged rows removed from the list upon a successful drop. To accomplish this, we first want to setup the initial list of items for our draggable ListView via useListData so that we have access to some helper methods to modify the list of items on the fly. Note that this is completely optional and is not required to enable drag and drop in React Spectrum. You may substitute useListData with useAsyncList or with any other state management solution.

let list = useListData({
  initialItems: [
    {id: 'a', textValue: 'Adobe Photoshop'},
    {id: 'b', textValue: 'Adobe XD'},
    {id: 'c', textValue: 'Adobe Dreamweaver'},
    {id: 'd', textValue: 'Adobe InDesign'},
    {id: 'e', textValue: 'Adobe Connect'}
  ]
});

let list = useListData({
  initialItems: [
    {id: 'a', textValue: 'Adobe Photoshop'},
    {id: 'b', textValue: 'Adobe XD'},
    {id: 'c', textValue: 'Adobe Dreamweaver'},
    {id: 'd', textValue: 'Adobe InDesign'},
    {id: 'e', textValue: 'Adobe Connect'}
  ]
});

let list = useListData({
  initialItems: [
    {
      id: 'a',
      textValue:
        'Adobe Photoshop'
    },
    {
      id: 'b',
      textValue:
        'Adobe XD'
    },
    {
      id: 'c',
      textValue:
        'Adobe Dreamweaver'
    },
    {
      id: 'd',
      textValue:
        'Adobe InDesign'
    },
    {
      id: 'e',
      textValue:
        'Adobe Connect'
    }
  ]
});

Next, we need to specify the data associated with each dragged item by returning an array from the getItems function. As described above in the concepts section, each item includes a mapping of drag types to serialized data. In this case, we look up the information for each dragged item and serialize it, mapping it to a custom item type. This information will be processed and provided to the drop target's drop handlers on drop.

function getItems(keys) {
  return [...keys].map(key => {
    let item = list.getItem(key);
    return {
      'adobe-app': JSON.stringify(item)
    };
  })
}

function getItems(keys) {
  return [...keys].map(key => {
    let item = list.getItem(key);
    return {
      'adobe-app': JSON.stringify(item)
    };
  })
}

function getItems(keys) {
  return [...keys].map(
    (key) => {
      let item = list
        .getItem(key);
      return {
        'adobe-app': JSON
          .stringify(
            item
          )
      };
    }
  );
}

We also create an onDragEnd event handler for useDnDHooks that handles removing the dragged items from the draggable list upon a successful drop operation. Note how we use the .remove method provided by useListData to remove the dropped items from our list.

function onDragEnd(e) {
  if (e.dropOperation === 'move') {
    list.remove(...e.keys);
  }
}

function onDragEnd(e) {
  if (e.dropOperation === 'move') {
    list.remove(...e.keys);
  }
}

function onDragEnd(e) {
  if (
    e.dropOperation ===
      'move'
  ) {
    list.remove(
      ...e.keys
    );
  }
}

Finally, we provide our getItems and onDragEnd functions as options to useDnDHooks, providing us with a set of dragHooks that we can pass to our ListView directly. Below is what our draggable ListView would look like after combining everything together. For more info on getItems and onDragEnd, see the API section below.

import {Item, ListView} from '@react-spectrum/list';
import {useDnDHooks} from '@react-spectrum/dnd';
import {useListData} from '@react-stately/data';

function DraggableList(props) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData({
    initialItems: items || [
      {id: 'a', textValue: 'Adobe Photoshop'},
      {id: 'b', textValue: 'Adobe XD'},
      {id: 'c', textValue: 'Adobe Dreamweaver'},
      {id: 'd', textValue: 'Adobe InDesign'},
      {id: 'e', textValue: 'Adobe Connect'}
    ]
  });

  let {dragHooks} = useDnDHooks({
    getItems: (keys) => [...keys].map(key => {
      let item = list.getItem(key);
      return {
        'adobe-app': JSON.stringify(item)
      };
    }),
    onDragEnd: (e) => {
      if (e.dropOperation === 'move') {
        list.remove(...e.keys);
      }
    }
  });

  return (
    <ListView
      aria-label="Draggable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dragHooks={dragHooks}
      {...otherProps}>
      {item => (
        <Item key={item.key}>
          {item.textValue}
        </Item>
      )}
    </ListView>
  );
}

import {Item, ListView} from '@react-spectrum/list';
import {useDnDHooks} from '@react-spectrum/dnd';
import {useListData} from '@react-stately/data';

function DraggableList(props) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData({
    initialItems: items || [
      {id: 'a', textValue: 'Adobe Photoshop'},
      {id: 'b', textValue: 'Adobe XD'},
      {id: 'c', textValue: 'Adobe Dreamweaver'},
      {id: 'd', textValue: 'Adobe InDesign'},
      {id: 'e', textValue: 'Adobe Connect'}
    ]
  });

  let {dragHooks} = useDnDHooks({
    getItems: (keys) => [...keys].map(key => {
      let item = list.getItem(key);
      return {
        'adobe-app': JSON.stringify(item)
      };
    }),
    onDragEnd: (e) => {
      if (e.dropOperation === 'move') {
        list.remove(...e.keys);
      }
    }
  });

  return (
    <ListView
      aria-label="Draggable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dragHooks={dragHooks}
      {...otherProps}>
      {item => (
        <Item key={item.key}>
          {item.textValue}
        </Item>
      )}
    </ListView>
  );
}

import {
  Item,
  ListView
} from '@react-spectrum/list';
import {useDnDHooks} from '@react-spectrum/dnd';
import {useListData} from '@react-stately/data';

function DraggableList(
  props
) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData(
    {
      initialItems:
        items || [
          {
            id: 'a',
            textValue:
              'Adobe Photoshop'
          },
          {
            id: 'b',
            textValue:
              'Adobe XD'
          },
          {
            id: 'c',
            textValue:
              'Adobe Dreamweaver'
          },
          {
            id: 'd',
            textValue:
              'Adobe InDesign'
          },
          {
            id: 'e',
            textValue:
              'Adobe Connect'
          }
        ]
    }
  );

  let { dragHooks } =
    useDnDHooks({
      getItems: (keys) =>
        [...keys].map(
          (key) => {
            let item =
              list
                .getItem(
                  key
                );
            return {
              'adobe-app':
                JSON
                  .stringify(
                    item
                  )
            };
          }
        ),
      onDragEnd: (e) => {
        if (
          e.dropOperation ===
            'move'
        ) {
          list.remove(
            ...e.keys
          );
        }
      }
    });

  return (
    <ListView
      aria-label="Draggable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dragHooks={dragHooks}
      {...otherProps}
    >
      {(item) => (
        <Item
          key={item.key}
        >
          {item
            .textValue}
        </Item>
      )}
    </ListView>
  );
}

Creating the droppable list#

For the second ListView, we want to make it droppable but have it only accept root level drops. Similar to the draggable ListView, we'll start by initializing the default item list via useListData. As a reminder, useListData is completely optional here and can be replaced by useAsyncList or any other state management solution.

let list = useListData({
  initialItems: [
    {id: 'f', textValue: 'Adobe AfterEffects'},
    {id: 'g', textValue: 'Adobe Illustrator'},
    {id: 'h', textValue: 'Adobe Lightroom'},
    {id: 'i', textValue: 'Adobe Premiere Pro'},
    {id: 'j', textValue: 'Adobe Fresco'}
  ]
});

let list = useListData({
  initialItems: [
    {id: 'f', textValue: 'Adobe AfterEffects'},
    {id: 'g', textValue: 'Adobe Illustrator'},
    {id: 'h', textValue: 'Adobe Lightroom'},
    {id: 'i', textValue: 'Adobe Premiere Pro'},
    {id: 'j', textValue: 'Adobe Fresco'}
  ]
});

let list = useListData({
  initialItems: [
    {
      id: 'f',
      textValue:
        'Adobe AfterEffects'
    },
    {
      id: 'g',
      textValue:
        'Adobe Illustrator'
    },
    {
      id: 'h',
      textValue:
        'Adobe Lightroom'
    },
    {
      id: 'i',
      textValue:
        'Adobe Premiere Pro'
    },
    {
      id: 'j',
      textValue:
        'Adobe Fresco'
    }
  ]
});

To implement root level only drops, we create a getDropOperation function that returns "cancel" for any drop targets other than root or if the dragged item types doesn't include 'adobe-app'.

function getDropOperation(target, types) {
  if (target.type !== 'root' || !types.has('adobe-app')) {
    return 'cancel';
  }

  return 'move';
}

function getDropOperation(target, types) {
  if (target.type !== 'root' || !types.has('adobe-app')) {
    return 'cancel';
  }

  return 'move';
}

function getDropOperation(
  target,
  types
) {
  if (
    target.type !==
      'root' ||
    !types.has(
      'adobe-app'
    )
  ) {
    return 'cancel';
  }

  return 'move';
}

Next, we create an onDrop event handler to process the successfully dropped items. This onDrop handler first checks each dropped item's kind and type, extracting the item's relevant information if it detects it has the expected types. This information is used to construct an array of items to insert to the end of the droppable list via list.append.

async function onDrop(e) {
  let itemsToAdd = await Promise.all(
    e.items
      .filter(item => item.kind === 'text' && item.types.has('adobe-app'))
      .map(async item => JSON.parse(await item.getText('adobe-app')))
  );
  list.append(...itemsToAdd);
}

async function onDrop(e) {
  let itemsToAdd = await Promise.all(
    e.items
      .filter((item) =>
        item.kind === 'text' && item.types.has('adobe-app')
      )
      .map(async (item) =>
        JSON.parse(await item.getText('adobe-app'))
      )
  );
  list.append(...itemsToAdd);
}

async function onDrop(
  e
) {
  let itemsToAdd =
    await Promise.all(
      e.items
        .filter((item) =>
          item.kind ===
            'text' &&
          item.types.has(
            'adobe-app'
          )
        )
        .map(
          async (item) =>
            JSON.parse(
              await item
                .getText(
                  'adobe-app'
                )
            )
        )
    );
  list.append(
    ...itemsToAdd
  );
}

Finally, we provide our getDropOperation and onDrop functions as options to useDnDHooks, providing us with a set of dropHooks that we can pass to our ListView directly. Below is what our droppable ListView would look like after combining everything together. For more info on getDropOperation and onDrop, see the API section below.

import {useDnDHooks} from '@react-spectrum/dnd';

function DroppableList(props) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData({
    initialItems: items || [
      {id: 'f', textValue: 'Adobe AfterEffects'},
      {id: 'g', textValue: 'Adobe Illustrator'},
      {id: 'h', textValue: 'Adobe Lightroom'},
      {id: 'i', textValue: 'Adobe Premiere Pro'},
      {id: 'j', textValue: 'Adobe Fresco'}
    ]
  });

  let {dropHooks} = useDnDHooks({
    getDropOperation: (target, types) => {
      if (target.type !== 'root' || !types.has('adobe-app')) {
        return 'cancel';
      }

      return 'move';
    },
    onDrop: async (e) => {
      let itemsToAdd = await Promise.all(
        e.items
          .filter(item => item.kind === 'text' && item.types.has('adobe-app'))
          .map(async item => JSON.parse(await item.getText('adobe-app')))
      );
      list.append(...itemsToAdd);
    }
  });

  return (
    <ListView
      aria-label="Droppable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dropHooks={dropHooks}
      {...otherProps}>
      {item => (
        <Item key={item.key}>
          {item.textValue}
        </Item>
      )}
    </ListView>
  );
}

import {useDnDHooks} from '@react-spectrum/dnd';

function DroppableList(props) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData({
    initialItems: items || [
      { id: 'f', textValue: 'Adobe AfterEffects' },
      { id: 'g', textValue: 'Adobe Illustrator' },
      { id: 'h', textValue: 'Adobe Lightroom' },
      { id: 'i', textValue: 'Adobe Premiere Pro' },
      { id: 'j', textValue: 'Adobe Fresco' }
    ]
  });

  let { dropHooks } = useDnDHooks({
    getDropOperation: (target, types) => {
      if (
        target.type !== 'root' || !types.has('adobe-app')
      ) {
        return 'cancel';
      }

      return 'move';
    },
    onDrop: async (e) => {
      let itemsToAdd = await Promise.all(
        e.items
          .filter((item) =>
            item.kind === 'text' &&
            item.types.has('adobe-app')
          )
          .map(async (item) =>
            JSON.parse(await item.getText('adobe-app'))
          )
      );
      list.append(...itemsToAdd);
    }
  });

  return (
    <ListView
      aria-label="Droppable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dropHooks={dropHooks}
      {...otherProps}
    >
      {(item) => (
        <Item key={item.key}>
          {item.textValue}
        </Item>
      )}
    </ListView>
  );
}

import {useDnDHooks} from '@react-spectrum/dnd';

function DroppableList(
  props
) {
  let {
    items,
    ...otherProps
  } = props;
  let list = useListData(
    {
      initialItems:
        items || [
          {
            id: 'f',
            textValue:
              'Adobe AfterEffects'
          },
          {
            id: 'g',
            textValue:
              'Adobe Illustrator'
          },
          {
            id: 'h',
            textValue:
              'Adobe Lightroom'
          },
          {
            id: 'i',
            textValue:
              'Adobe Premiere Pro'
          },
          {
            id: 'j',
            textValue:
              'Adobe Fresco'
          }
        ]
    }
  );

  let { dropHooks } =
    useDnDHooks({
      getDropOperation: (
        target,
        types
      ) => {
        if (
          target.type !==
            'root' ||
          !types.has(
            'adobe-app'
          )
        ) {
          return 'cancel';
        }

        return 'move';
      },
      onDrop: async (
        e
      ) => {
        let itemsToAdd =
          await Promise
            .all(
              e.items
                .filter(
                  (item) =>
                    item
                        .kind ===
                      'text' &&
                    item
                      .types
                      .has(
                        'adobe-app'
                      )
                )
                .map(
                  async (item) =>
                    JSON
                      .parse(
                        await item
                          .getText(
                            'adobe-app'
                          )
                      )
                )
            );
        list.append(
          ...itemsToAdd
        );
      }
    });

  return (
    <ListView
      aria-label="Droppable list view example"
      width="size-3600"
      height="size-3600"
      selectionMode="multiple"
      items={list.items}
      dropHooks={dropHooks}
      {...otherProps}
    >
      {(item) => (
        <Item
          key={item.key}
        >
          {item
            .textValue}
        </Item>
      )}
    </ListView>
  );
}

API#

As seen in the example above, enabling drag and drop for a supported React Spectrum component differs slightly from the typical event handler prop pattern that you may be familiar with. Instead of providing each event handler directly to the component, you must first import useDnDHooks from the @react-spectrum/dnd package and provide this hook with your desired options. useDnDHooks will then provide you with a set of drag hooks that you can pass to the component via its dragHooks prop, thus enabling drag operations for the component. Drop operations are then enabled in the same way by passing the drop hooks from useDnDHooks to the component's dropHooks prop. This approach allows the drag and drop implementation to be included only when used, keeping bundle sizes small when unused by an application.

useDnDHooks#

TODO: Update this section to better separate the util handlers from the lower level props

useDnDHooks(
  (options: DnDOptions
)): DnDHooks

Name	Type	Default	Description
`getItems`	`( (keys: Set<Key> )) => DragItem[]`	`() => []`	A function that returns the items being dragged. If not specified, we assume that the collection is not draggable.
`onDragStart`	`( (e: DraggableCollectionStartEvent )) => void`	—	Handler that is called when a drag operation is started.
`onDragMove`	`( (e: DraggableCollectionMoveEvent )) => void`	—	Handler that is called when the dragged element 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.
`getAllowedDropOperations`	`() => DropOperation[]`	—	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.
`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.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters the drop target.
`onDropMove`	`( (e: DroppableCollectionMoveEvent )) => void`	—	Handler that is called when a valid drag is moved within the drop target.
`onDropActivate`	`( (e: DroppableCollectionActivateEvent )) => void`	—	Handler that is called after a valid drag is held over the drop target for a period of time.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits the drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on the drop target.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler called when external items are dropped "between" the droppable collection's items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler called when items are dropped "on" a droppable collection's item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler called when items are reordered via drag in the source collection.
`acceptedDragTypes`	`'all' \| Array<string>`	`'all'`	The drag types that the droppable collection accepts. If directories are accepted, include the DIRECTORY_DRAG_TYPE from @react-aria/dnd in the array of allowed types.
`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.

Of the various hook options above, getAllowedDropOperations and getDropOperation may be of particular interest since it allows you to specify what kinds of drag and drop operations you want to allow. When the dragged items are dropped on a drop target created using the React Aria drag and drop hooks, the allowed drop operations you return in getAllowedDropOperations are provided to the drop target's getDropOperation, giving the drop target extra information to use when deciding what drop operation to execute. This in turn provides the onDragEnd and onDrop handlers with the executed drop operation, allowing you to decide what to do with the dragged items in your original collection and in the dropped collection.

For instance, you may have a draggable collection of items that allows "move" and "copy" operations but you need a way to know whether or not you should be removing the dragged items from the list after a drop operation. A drop target that only allows "copy" operations, such as a file upload drop zone, would be able to return "copy" from its getDropOperation and communicate that to your draggable collection's onDragEnd handler, letting the draggable collection know that it shouldn't remove the dragged items from its list. Alternatively, a drop target that allows "move" operations, like in the example above, would return move from its getDropOperation and thus inform your draggable collection to remove the dragged items from its list.

Supported components#

The following list shows which components currently support drag and drop. Common drag and drop implementations are included in each component's documentation so definitely take a look!

ListView

Name	Type	Default	Description
`getItems`	`( (keys: Set<Key> )) => DragItem[]`	`() => []`	A function that returns the items being dragged. If not specified, we assume that the collection is not draggable.
`onDragStart`	`( (e: DraggableCollectionStartEvent )) => void`	—	Handler that is called when a drag operation is started.
`onDragMove`	`( (e: DraggableCollectionMoveEvent )) => void`	—	Handler that is called when the dragged element 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.
`getAllowedDropOperations`	`() => DropOperation[]`	—	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.
`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.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters the drop target.
`onDropMove`	`( (e: DroppableCollectionMoveEvent )) => void`	—	Handler that is called when a valid drag is moved within the drop target.
`onDropActivate`	`( (e: DroppableCollectionActivateEvent )) => void`	—	Handler that is called after a valid drag is held over the drop target for a period of time.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits the drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on the drop target.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler called when external items are dropped "between" the droppable collection's items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler called when items are dropped "on" a droppable collection's item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler called when items are reordered via drag in the source collection.
`acceptedDragTypes`	`'all' \| Array<string>`	`'all'`	The drag types that the droppable collection accepts. If directories are accepted, include the DIRECTORY_DRAG_TYPE from @react-aria/dnd in the array of allowed types.
`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.

Name	Type	Description
`type`	`string`

Name	Type	Description
`keys`	`Set<Key>`
`type`	`'dragstart'`
`x`	`number`
`y`	`number`

Name	Type	Description
`keys`	`Set<Key>`
`type`	`'dragmove'`
`x`	`number`
`y`	`number`

Name	Type	Description
`keys`	`Set<Key>`
`isInternal`	`boolean`
`type`	`'dragend'`
`dropOperation`	`DropOperation`
`x`	`number`
`y`	`number`

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

RootDropTarget | ItemDropTarget

Name	Type	Description
`type`	`'root'`

Name	Type	Description
`type`	`'item'`
`key`	`Key`
`dropPosition`	`DropPosition`

'on'
  | 'before'
  | 'after'

Method	Description
`has( (type: string )): boolean`

Name	Type	Description
`target`	`DropTarget`
`type`	`'dropenter'`
`x`	`number`
`y`	`number`

Name	Type	Description
`target`	`DropTarget`
`type`	`'dropmove'`
`x`	`number`
`y`	`number`

Name	Type	Description
`target`	`DropTarget`
`type`	`'dropactivate'`
`x`	`number`
`y`	`number`

Name	Type	Description
`target`	`DropTarget`
`type`	`'dropexit'`
`x`	`number`
`y`	`number`

Name	Type	Description
`target`	`DropTarget`
`type`	`'drop'`
`dropOperation`	`DropOperation`
`items`	`DropItem[]`
`x`	`number`
`y`	`number`

TextItem
  | FileItem
  | DirectoryItem

Name	Type	Description
`kind`	`'text'`
`types`	`Set<string>`

Method	Description
`getText( (type: string )): Promise<string>`

Name	Type	Description
`kind`	`'file'`
`type`	`string`
`name`	`string`

Method	Description
`getFile(): Promise<File>`
`getText(): Promise<string>`

Name	Type	Description
`kind`	`'directory'`
`name`	`string`

Method	Description
`getEntries(): AsyncIterable<FileItem \| DirectoryItem>`

Name	Type	Description
`items`	`DropItem[]`
`dropOperation`	`DropOperation`
`target`	`ItemDropTarget`

Name	Type	Description
`items`	`DropItem[]`
`dropOperation`	`DropOperation`

Name	Type	Description
`items`	`DropItem[]`
`dropOperation`	`DropOperation`
`isInternal`	`boolean`
`target`	`ItemDropTarget`

Name	Type	Description
`keys`	`Set<Key>`
`dropOperation`	`DropOperation`
`target`	`ItemDropTarget`

Name	Type	Description
`dndHooks`	`DragHooks & DropHooks & {isVirtualDragging?: () => boolean }`

Name Type Description

useDraggableCollectionState

(
  (props: Name Type Description
collection Collection<Node<unknown>> 
selectionManager MultipleSelectionManager 
onDragStart (
    (e: DraggableCollectionStartEvent
  )) => void Handler that is called when a drag operation is started.
onDragMove (
    (e: DraggableCollectionMoveEvent
  )) => void Handler that is called when the dragged element 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> 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.
<DraggableCollectionStateOptions, 'getItems'>
)) => DraggableCollectionState

useDraggableCollection ( props: DraggableCollectionOptions, state: DraggableCollectionState, ref: RefObject<HTMLElement> ) => void

useDraggableItem ( (props: DraggableItemProps, , state: DraggableCollectionState )) => DraggableItemResult

DragPreview

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

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`	Get an item by its key.
`at( (idx: number )): T`	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.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`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`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

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.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , 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'

'selection' | 'all'

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.

'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.

'first' | 'last'

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

Name	Type	Description
`collection`	`Collection<Node<unknown>>`
`selectionManager`	`MultipleSelectionManager`
`getItems`	`( (keys: Set<Key> )) => DragItem[]`	A function that returns the items being dragged.
`onDragStart`	`( (e: DraggableCollectionStartEvent )) => void`	Handler that is called when a drag operation is started.
`onDragMove`	`( (e: DraggableCollectionMoveEvent )) => void`	Handler that is called when the dragged element 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>`	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.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`
`selectionManager`	`MultipleSelectionManager`
`draggedKey`	`Key \| null`
`draggingKeys`	`Set<Key>`
`preview`	`RefObject<DragPreviewRenderer>`
`getAllowedDropOperations`	`() => DropOperation[]`

Methods

Method	Description
`isDragging( (key: Key )): boolean`
`getKeysForDrag( (key: Key )): Set<Key>`
`getItems( (key: Key )): DragItem[]`
`startDrag( (key: Key, , event: DragStartEvent )): void`
`moveDrag( (event: DragMoveEvent )): void`
`endDrag( (event: DraggableCollectionEndEvent )): void`

Name	Type	Description
`type`	`'dragstart'`
`x`	`number`
`y`	`number`

Name	Type	Description
`type`	`'dragmove'`
`x`	`number`
`y`	`number`

Name	Type	Description
`key`	`Key`	The key of the draggable item within the collection.
`hasDragButton`	`boolean`	Whether the item has an explicit focusable drag affordance to initiate accessible drag and drop mode. If true, the dragProps will omit these event handlers, and they will be applied to dragButtonProps instead.
`hasAction`	`boolean`	Whether the item has a primary action (e.g. Enter key or long press) that would conflict with initiating accessible drag and drop. If true, the Alt key must be held to start dragging with a keyboard, and long press is disabled until selection mode is entered. This should be passed from the associated collection item hook (e.g. useOption, useGridListItem, etc.).

Name	Type	Description
`dragProps`	`HTMLAttributes<HTMLElement>`
`dragButtonProps`	`AriaButtonProps`

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`ElementType \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`useDroppableCollectionState`	`( (props: DroppableCollectionStateOptions )) => DroppableCollectionState`
`useDroppableCollection`	`( props: DroppableCollectionOptions, state: DroppableCollectionState, ref: RefObject<HTMLElement> ) => DroppableCollectionResult`
`useDroppableItem`	`( options: DroppableItemOptions, state: DroppableCollectionState, ref: RefObject<HTMLElement> ) => DroppableItemResult`
`useDropIndicator`	`( props: DropIndicatorProps, state: DroppableCollectionState, ref: RefObject<HTMLElement> ) => DropIndicatorAria`

Name	Type	Default	Description
`collection`	`Collection<Node<unknown>>`	—
`selectionManager`	`MultipleSelectionManager`	—
`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.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters the drop target.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits the drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on the drop target.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler called when external items are dropped "between" the droppable collection's items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler called when items are dropped "on" a droppable collection's item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler called when items are reordered via drag in the source collection.
`acceptedDragTypes`	`'all' \| Array<string>`	`'all'`	The drag types that the droppable collection accepts. If directories are accepted, include the DIRECTORY_DRAG_TYPE from @react-aria/dnd in the array of allowed types.
`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.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`
`selectionManager`	`MultipleSelectionManager`
`target`	`DropTarget`

Methods

Method	Description
`setTarget( (target: DropTarget )): void`
`isDropTarget( (target: DropTarget )): boolean`
`getDropOperation( (e: DropOperationEvent )): DropOperation`

Name	Type	Description
`target`	`DropTarget`
`types`	`DragTypes`
`allowedOperations`	`DropOperation[]`
`isInternal`	`boolean`
`draggingKeys`	`Set<Key>`

Name	Type	Default	Description
`keyboardDelegate`	`KeyboardDelegate`	—
`dropTargetDelegate`	`DropTargetDelegate`	—
`onDropActivate`	`( (e: DroppableCollectionActivateEvent )) => void`	—	Handler that is called after a valid drag is held over the drop target for a period of time.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on the drop target.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler called when external items are dropped "between" the droppable collection's items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler called when items are dropped "on" a droppable collection's item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler called when items are reordered via drag in the source collection.
`acceptedDragTypes`	`'all' \| Array<string>`	`'all'`	The drag types that the droppable collection accepts. If directories are accepted, include the DIRECTORY_DRAG_TYPE from @react-aria/dnd in the array of allowed types.
`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.

Method	Description
`getKeyBelow( (key: Key )): Key \| null`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key \| null`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key \| null`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key \| null`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key \| null`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key \| null`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key )): Key \| null`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

Method	Description
`getDropTargetFromPoint( x: number, y: number, isValidDropTarget: ( (target: DropTarget )) => boolean ): DropTarget \| null`	Returns a drop target within a collection for the given x and y coordinates. The point is provided relative to the top left corner of the collection container. A drop target can be checked to see if it is valid using the provided `isValidDropTarget` function.