dnd-kit / docs

Official documentation for @dnd-kit

description
@dnd-kit – A lightweight, modular, performant, accessible and extensible drag & drop toolkit for React.

Overview

• Feature packed: customizable collision detection algorithms, multiple activators, draggable overlay, drag handles, auto-scrolling, constraints, and so much more.
• Built for React: exposes hooks such as useDraggable and useDroppable, and won't require you to re-architect your app or create additional wrapper DOM nodes.
• Supports a wide range of use cases: lists, grids, multiple containers, nested contexts, variable sized items, virtualized lists, 2D Games, and more.
• Zero dependencies and modular: the core of the library weighs around 10kb minified and has no external dependencies. It's built around built-in React state management and context, which keeps the library lean.
• Built-in support for multiple input methods: Pointer, mouse, touch and keyboard sensors.
• Fully customizable & extensible: Customize every detail – animations, transitions, behaviours, styles. Build your own sensors, collision detection algorithms, customize key bindings and so much more.
• Accessibility: Keyboard support, sensible default aria attributes, customizable screen reader instructions and live regions built-in.
• Performance: It was built with performance in mind in order to support silky smooth animations.
• Presets: Need to build a sortable interface? Check out @dnd-kit/sortable, which is a thin layer built on top of @dnd-kit/core. More presets coming in the future.

The core library of dnd kit exposes two main concepts:

• Draggable elements
• Droppable areas

Augment your existing components using the useDraggable and useDroppable hooks, or combine both to create components that can both be dragged and dropped over.

Handle events and customize the behaviour of your draggable elements and droppable areas using the <DndContext> provider. Configure sensors to handle different input methods.

Use the <DragOverlay> component to render a draggable overlay that is removed from the normal document flow and is positioned relative to the viewport.

Check out our quick start guide to learn how get started:

{% content-ref url="introduction/getting-started.md" %} getting-started.md {% endcontent-ref %}

Extensibility

Extensibility is at the core of dnd kit. It was built to be lean and extensible. It ships with the features we believe most people will want most of the time, and provides extension points to build the rest on top of @dnd-kit/core.

A prime example of the level of extensibility of dnd kit is the Sortable preset, which is built using the extension points that are exposed by @dnd-kit/core.

The primary extension points are:

• Sensors
• Modifiers
• Custom collision detection algorithms

Accessibility

Building drag and drop interfaces that are accessible to everyone isn't easy, and requires thoughtful consideration.

The @dnd-kit/core library provides a number of starting points to help you make your drag and drop interfaces accessible:

• Keyboard support out of the box
• Customizable screen reader instructions for how to interact with draggable items
• Customizable live region updates to provide screen reader announcements in real-time of what is currently happening with draggable and droppable elements.
• Sensible defaults for attributes that should be passed to draggable elements

Check out our Accessibility guide to learn more about how you can help make your drag and drop interface accessible for everyone:

{% content-ref url="guides/accessibility.md" %} accessibility.md {% endcontent-ref %}

Architecture

Unlike many drag and drop libraries, dnd kit is **** intentionally not built on top of the HTML5 Drag and drop API. This was a deliberate architectural decision, that does come with tradeoffs that you should be aware of before deciding to use it. For most web applications, we believe the benefits outweigh the tradeoffs.

The HTML5 Drag and drop API has some severe limitations. It does not support touch devices, which means that the libraries that are built on top of it need to expose an entirely different implementation to support touch devices. This typically increases the complexity of the codebase and the overall bundle size of the library. Further, it requires workarounds to implement common use cases such as customizing the drag preview, locking dragging to a specific axis or to the bounds of a container, or animating the dragged item as it is picked up.

The main tradeoff with not using the HTML5 Drag and drop API is that you won't be able to drag from the desktop or between windows. If the drag and drop use-case you have in mind involves this kind of functionality, you'll definitely want to use a library that's built on top of the HTML 5 Drag and drop API. We highly recommend you check out react-dnd for a React library that's has a native HTML 5 Drag and drop backend.

Performance

Minimizing DOM mutations

dnd kit lets you build drag and drop interfaces without having to mutate the DOM every time an item needs to shift position.

This is possible because dnd kit lazily calculates and stores the initial positions and client rects of your droppable containers when a drag operation is initiated. These positions are passed down to your components that use useDraggable and useDroppable so that you can compute the new positions of your items while a drag operation is underway, and move them to their new positions using performant CSS properties that do not trigger a repaint such as translate3d and scale. For an example of how this can be achieved, check out the implementation of the sorting strategies that are exposed by the @dnd-kit/sortable library.

This isn't to say that you can't shift the position of the items in the DOM while dragging, this is something that is supported and sometimes inevitable. In some cases, it won't be possible to know in advance what the new position and layout of the item until you move it in the DOM. Just know that these kind of mutations to the DOM while dragging are much more expensive and will cause a repaint, so if possible, prefer computing the new positions using translate3d and scale.

Synthetic events

Sensors use SyntheticEvent listeners for the activator events of all sensors, which leads to improved performance over manually adding event listeners to each individual draggable node.

docs's Issues

Question, how i possibile click a item without move it?

How is possibile click a item without moving it and trigger the drag and drop?

let's say, I have a card with two buttons, I can't click on the buttons because the card moves so i can't trigger functions from these button.. how i can do this?

Conflicting recommendations for touch-action

Just spotted some conflicting recommendations for using the touch-action property on draggable items, and wondering which should be used?

On the Touch Sensor's recommendations, using touch-action: manipulation is recommended, whereas on the Draggable recommendations, using touch-action: none is recommended.

(Also, I noticed that the call out on the Draggable recommendations mentions preventing scrolling; however, given that sometimes draggable items need to be draggable within a scrollable container, this call out gets a little unclear to me as to whether I would want to disable scrolling the first place.)

Thank you!

draggable item disappear on drag

i have a conditional rendering for dragOverlay component but when I drag the item the draggable item disappears however I cancel the dragging process how can I fix this issue please.

here's my code .

function AreaContainer({ area }: AreaProps) {
const [activeId, setActiveId] = useState<string | null>(null);
const [overId, setOverId] = useState<string | null>(null);
const { setNodeRef } = useDroppable({
   id: area.id,
   data: {
     type: "Area",
     area,
   },
});

  useDndMonitor({
     onDragStart(event) {
      setActiveId(event.active.id.toString());
  },
   onDragEnd(event) {
      setActiveId(null);
    },
   onDragOver(event) {
     setOverId(event.over?.id.toString() ?? null);
    },
   onDragCancel(event) {
      setOverId(null);
      setActiveId(null);
     },
 });

  const branch = branchesData.find((branch) => branch.id === +activeId!);

   return (
        <Card key={area.id} className="flex flex-col gap-4" ref={setNodeRef}>
              <CardHeader className="border-b">
                    <CardTitle>Area: {area.name}</CardTitle>
                    <CardDescription>Senior area manager Name</CardDescription>
             </CardHeader>
           <CardContent className="flex flex-col gap-4">
                  {branchesData
                        .filter((branch) => branch.area === area.id)
                        .map((branch) => (
                                <BranchContainer branch={branch} key={branch.id} />
                   ))}

             <DragOverlay>
                   {activeId ? (
                          <Badge className="w-full py-3" variant="secondary">
                                  {branch?.name}
                          </Badge>
                      ) : null}
             </DragOverlay>
         </CardContent>
      </Card>
   );
 }

Question, how i can render a different element before the drop?

I'm moving an item from one column to another,
I would like to see a different item in the other column when I move the card closer to it,

for example, I would like to see a +. instead of the card I'm moving

i have only to see the card y in the drag overlay and once I drop it in the other column

do i need to create something custom, like creating fake elements in the various arrays (by current index, position) or is there any way to do this?

Element displacement when parent has transform propery

Hello folks I faced with a problem when element losing its correct position if its parent has a transform property

I created codesandbox to show what I mean. Here I kinda simulating that my list can be in a popup that is floating and in positionig styles uses transform property. For example in my real app I use floating-ui hook to place my popup and its kinda ruining the styles of dnd.

Any ideas here what to do? I tried to create custom modifiers, but can not catch or check parents styles.

Add typescript code examples

All code examples are written only in .jsx.
It wouldnt be much hussle for You to also provide them in .tsx but would save a lot of time for developers using your package.

Correcting Typo: [api-documentation/context-provider/README.md]

Link Github Repo and Storybook in Docs

Using the docs, I wasn't able to find any Github link, so I had to google for the Repo in order to find it. Inserting a Github Link to the repo (not the repo for the docs but the one for the toolkit) would fix this.

Also I would recommend adding a link to the playground as well.

Dark mode?

Feature request: dark mode for the documentation

Data typing

Hi, I'm using dnd-kit in a TypeScript project, and would like to strongly type the data property attached to Draggable objects.

I tried extending the interface, the way other libraries sometimes implement it, but it didn't work.

declare module '@dnd-kit/core/dist/store/types' {
    export interface Active {
        data: DataRef<MyDataType>;
    }
}

TypeScript gives an error Subsequent property declarations must have the same type. Property 'data' must be of type 'DataRef<AnyData>', but here has type 'DataRef<MyDataType>'.

It would be great if a future version could expose an API for either extending the interface, or at passing generics to the DnDContext component.

Question: Sortable with virtualization?

Hi,

Do you have some sample with huge array list to sort, which require virtualization? currently i find it my UI is lagging, ty

树结构拖拽问题

当我拖动树结构中某一个子节点时，会造成相邻的一个子节点跑到当前树外部去，放开鼠标拖动完成后，它又回来了，有时会有树外部节点进入，松开鼠标后，后回到原位


``

Fix documentation about CSS.Transform.toString(transform)

According to this issue you should use CSS.Translate.toString(transform) instead of CSS.Transform.toString(transform) to prevent scale transformation issues.

I would like to suggest to replace all CSS.Transform.toString(transform) in the documentation to CSS.Translate.toString(transform) as default. All examples in the clauderic/dnd-kit repository are also using this.