LogoLogo
ExamplesExperimentalCommunityGithub
  • Overview
  • Introduction
    • Installation
    • Quick start
  • API Documentation
    • DndContext
      • Collision detection algorithms
      • useDndContext
      • useDndMonitor
    • Droppable
      • useDroppable
    • Draggable
      • useDraggable
      • Drag Overlay
    • Sensors
      • Pointer
      • Mouse
      • Touch
      • Keyboard
    • Modifiers
  • Presets
    • Sortable
      • Sortable Context
      • useSortable
  • Guides
    • Accessibility
Powered by GitBook
On this page
  • Application structure
  • Context provider
  • Nesting
  • Props
  • Event handlers
  • Accessibility
  • Autoscroll
  • Collision detection
  • Sensors
  • Modifiers
  • Layout measuring
Edit on Git
  1. API Documentation

DndContext

Last updated 4 years ago

Application structure

Context provider

In order for your your and components to interact with each other, you'll need to make sure that the part of your React tree that uses them is nested within a parent <DndContext> component. The <DndContext> provider makes use of the to share data between draggable and droppable components and hooks.

React context provides a way to pass data through the component tree without having to pass props down manually at every level.

Therefore, components that use , or will need to be nested within a DndContext provider.

They don't need to be direct descendants, but, there does need to be a parent <DndContext> provider somewhere higher up in the tree.

import React from 'react';
import {DndContext} from '@dnd-kit/core';

function App() {
  return (
    <DndContext>
      {/* Components that use `useDraggable`, `useDroppable` */}
    </DndContext>
  );
}

Nesting

You may also nest <DndContext> providers within other <DndContext> providers to achieve nested draggable/droppable interfaces that are independent of one another.

import React from 'react';
import {DndContext} from '@dnd-kit/core';

function App() {
  return (
    <DndContext>
      {/* Components that use `useDraggable`, `useDroppable` */}
      <DndContext>
        {/* ... */}
        <DndContext>
          {/* ... */}
        </DndContext>
      </DndContext>
    </DndContext>
  );
}

When nesting DndContext providers, keep in mind that the useDroppable and useDraggable hooks will only have access to the other draggable and droppable nodes within that context.

Props

interface Props {
  announcements?: Announcements;
  autoScroll?: boolean;
  cancelDrop?: CancelDrop;
  children?: React.ReactNode;
  collisionDetection?: CollisionDetection;
  layoutMeasuring?: Partial<LayoutMeasuring>;
  modifiers?: Modifiers;
  screenReaderInstructions?: ScreenReaderInstructions;
  sensors?: SensorDescriptor<any>[];
  onDragStart?(event: DragStartEvent): void;
  onDragMove?(event: DragMoveEvent): void;
  onDragOver?(event: DragOverEvent): void;
  onDragEnd?(event: DragEndEvent): void;
  onDragCancel?(): void;
}

Event handlers

As you can see from the list of props above, there are a number of different events emitted by <DndContext> that you can listen to and decide how to handle.

The main events you can listen to are:

onDragStart

onDragMove

onDragOver

onDragEnd

Fires after a draggable item is dropped.

This event contains information about the active draggable id along with information on whether the draggable item was dropped over.

Rather, it provides information about which draggable item was dropped and whether it was over a droppable container when it was dropped.

It is up to the consumer of DndContext to decide what to do with that information and how to react to it, for example, by updating (or not) its internal state in response to the event so that the items are declaratively rendered in a different parent droppable.

onDragCancel

Fires if a drag operation is cancelled, for example, if the user presses escape while dragging a draggable item.

Accessibility

For more details and best practices around accessibility of draggable and droppable components, read the accessibility section:

Announcements

Use the announcements prop to customize the screen reader announcements that are announced in the live region when draggable items are picked up, moved over droppable regions, and dropped.

The default announcements are:

const defaultAnnouncements = {
  onDragStart(id) {
    return `Picked up draggable item ${id}.`;
  },
  onDragOver(id, overId) {
    if (overId) {
      return `Draggable item ${id} was moved over droppable area ${overId}.`;
    }

    return `Draggable item ${id} is no longer over a droppable area.`;
  },
  onDragEnd(id, overId) {
    if (overId) {
      return `Draggable item was dropped over droppable area ${overId}`;
    }

    return `Draggable item ${id} was dropped.`;
  },
  onDragCancel(id) {
    return `Dragging was cancelled. Draggable item ${id} was dropped.`;
  },
}

While these default announcements are sensible defaults that should cover most simple use cases, you know your application best, and we highly recommend that you customize these to provide a screen reader experience that is more tailored to the use case you are building.

Screen reader instructions

Use the screenReaderInstructions prop to customize the instructions that are read to screen readers when the focus is moved

Autoscroll

Use the optional autoScroll boolean prop to temporarily or permanently disable auto-scrolling for all sensors used within this DndContext.

Collision detection

Use the collisionDetection prop to customize the collision detection algorithm used to detect collisions between draggable nodes and droppable areas within theDndContext provider.

The built-in collision detection algorithms are:

You may also build custom collision detection algorithms or compose existing ones.

To learn more, read the collision detection guide:

Sensors

Sensors are an abstraction to detect different input methods in order to initiate drag operations, respond to movement and end or cancel the operation.

To learn how to customize sensors or how to pass different sensors to DndContext, read the Sensors guide:

Modifiers

Modifiers let you dynamically modify the movement coordinates that are detected by sensors. They can be used for a wide range of use cases, for example:

  • Restricting motion to a single axis

  • Restricting motion to the draggable node container's bounding rectangle

  • Restricting motion to the draggable node's scroll container bounding rectangle

  • Applying resistance or clamping the motion

To learn more about how to use Modifiers, read the Modifiers guide:

Layout measuring

You can configure when and how often DndContext should measure its droppable elements by using the layoutMeasuring prop.

The frequency argument controls how frequently layouts should be measured. By default, layout measuring is set to optimized, which only measures layouts based on the strategy.

Specify one of the following strategies:

  • LayoutMeasuringStrategy.WhileDragging: Default behavior, only measure droppable elements right after dragging has begun.

    LayoutMeasuringStrategy.BeforeDragging: Measure droppable elements before dragging begins and right after it ends.

  • LayoutMeasuringStrategy.Always: Measure droppable elements before dragging begins, right after dragging has begun, and after it ends.

Example usage:

import {DndContext, LayoutMeasuringStrategy} from '@dnd-kit/core';

<DndContext layoutMeasuring={{strategy: LayoutMeasuringStrategy.Always}} />

If multiple DndContext providers are listening for the same event, events will be captured by the first DndContext that contains a that is activated by that event, similar to how .

Fires when a drag event that meets the for that happens, along with the unique identifier of the draggable element that was picked up.

Fires anytime as the item is moved. Depending on the activated , this could for example be as the is moved or the movement keys are pressed.

Fires when a item is moved over a container, along with the unique identifier of that droppable container.

If there are no when the draggable item is dropped, the over property will be null. If a collision is detected, the over property will contain the id of the droppable over which it was dropped.

It's important to understand that the onDragEnd event does not move items into containers.

Auto-scrolling may also be disabled on an individual sensor basis using the static property autoScrollEnabled of the sensor. For example, the manages scrolling internally, and therefore has the static property autoScrollEnabled set to false.

The default collision detection algorithm is the algorithm.

The default sensors used by DndContext are the and sensors.

Droppable
Draggable
React Context API
useDraggable
useDroppable
DragOverlay
Sensor
events bubble in the DOM
draggable
droppable
collisions detected
draggable
droppable
Accessibility
Keyboard sensor
Collision detection algorithms
Pointer
Keyboard
Sensors
Modifiers
sensor
draggable
Pointer
Keyboard
activation constraints
sensor
rectangle intersection
Rectangle intersection
Closest center
Closest corners