@hello-pangea/dnd Documentation

The core design philosophy of @hello-pangea/dnd is physicality. The library aims to simulate the movement of physical objects rather than digital UI elements. This manifests in several ways:

• No instant movement (no snapping): Items are never instantly moved. Instead, items animate out of the way during a drag, and items animate into their new positions upon drop.
• Movement-based positioning: Instead of using drop shadows, lines, or clones to indicate a drop location, the library uses the natural movement of items to communicate where a dragged item will land.
• Center of gravity logic: Dragging impact is determined by the item's center of gravity rather than the initial grab point. A list item is considered 'dragged over' when the center position of the dragging item crosses a boundary, and resting items move out of the way once the dragging item's center passes their edge.
• Natural cross-list movement: Keyboard movement between lists is driven by simulated inertia, gravity, and collisions rather than simple index-based logic.

The following community projects are based on react-beautiful-dnd and may have compatibility issues with future versions of @hello-pangea/dnd. They serve as inspiration or reference for implementing drag-and-drop features:

• Kanban Boards:
  • kanban-dnd: A Kanban style to-do list with custom lane creation and reordering.
  • Simple Trello: A Trello clone using the React ecosystem (Demo).
  • react-kanban: A customizable Kanban/Trello board library.
• Games:
  • A drag'n'drop Checkers game (Source).
• Testing Utilities:
  • react-beautiful-dnd-test-utils: Test utilities built with react-testing-library.

When a parent element has a CSS transform applied, the position: fixed used during dragging may result in incorrect positioning. To fix this, you can use the Cloning API to move the dragging item to a different DOM location (like document.body).

When using the Cloning API, the original <Draggable /> is removed during the drag, and a clone is rendered into a container specified by getContainerForClone (defaults to document.body).

Note: Using the Cloning API is required for compatibility with virtual lists. For best results, ensure the clone is the same size as the original item to prevent displacement issues.

function List(props) {
  const items = props.items;

  return (
    <Droppable
      droppableId="droppable"
      renderClone={(provided, snapshot, rubric) => (
        <div
          {...provided.draggableProps}
          {...provided.dragHandleProps}
          ref={provided.innerRef}
        >
          Item id: {items[rubric.source.index].id}
        </div >
      )}
    >
      {(provided) => (
        <div ref={provided.innerRef} {...provided.droppableProps}>
          {items.map((item) => (
            <Draggable draggableId={item.id} index={item.index}>
              {(provided, snapshot) => (
                <div
                  {...provided.draggableProps}
                  {...provided.dragHandleProps}
                  ref={provided.innerRef}
                >
                  Item id: {item.id}
                </div >
              )}
            </Draggable>
          ))}
        </div >
      )}
    </Droppable>
  );
}

Container Definition

A container is defined as either a <Droppable /> that is scrollable, a <Droppable /> that has a scroll parent, or the window itself.

Scrolling Constraints

• Large Draggables: If a <Draggable /> is larger than the container on the axis you are attempting to scroll, auto-scrolling on that specific axis will be disabled. For example, a <Draggable /> taller than the window height will prevent vertical auto-scrolling, but horizontal auto-scrolling will still function.
• Input Types: Auto-scrolling works for mouse, touch, and keyboard inputs. For keyboard users, the library manages a combination of <Droppable /> scrolling, window scrolling, and manual movements to ensure items reach their intended positions.
• iOS Limitation: On iOS (Webkit) browsers, users may experience a noticeable shaking effect during auto-scrolling due to a known Webkit bug.