Drag and Drop in Element Web#

Element Web's drag-and-drop system is built on @dnd-kit (@dnd-kit/abstract, @dnd-kit/dom, @dnd-kit/react), at version ^0.5.0 1. It is used exclusively in the grouped (treegrid) room list view and supports two drag interactions:

1. Moving rooms between sections — drag a room item and drop it on a section header 2
2. Reordering sections — drag a section header to a new position 3

Flat list mode has no drag-and-drop support; only the grouped (treegrid) layout wraps in a DragDropProvider 4.

All DnD code lives in the shared-components package under packages/shared-components/src/room-list/VirtualizedRoomListView/.

Key Source Files#

Sensor Configuration (PointerSensor & KeyboardSensor)#

Both sensors are configured on the DragDropProvider in VirtualizedRoomListView.tsx.

PointerSensor — uses the unified Pointer Events API, which handles mouse, touch, and stylus input without separate event listeners. It is configured with a 5 px activation distance so that a short tap or click does not accidentally start a drag 6.

KeyboardSensor — remapped to avoid conflicts with existing room-list shortcuts 7:

• Space — start and end drag (not Enter, which opens the room)
• Escape — cancel drag
• Arrow keys — move the dragged item
• Offset: 17 px per keypress (KEYBOARD_DRAG_OFFSET) instead of the dnd-kit default of 10 px, to avoid sluggish movement 8

During an active keyboard drag, useDragOperation is used to disable the room list's own keyboard navigation so arrow keys don't simultaneously scroll the list 9.

Drag Payload Types & Event Handling#

dragAndDrop.ts defines the discriminated union carried in every drag operation:

• RoomDragData — { type: "room" } — attached to each room list item 10
• SectionDragData — { type: "section"; index: number } — attached to section headers, carrying the section's current index for ordering logic 11
• isSectionDragData() — runtime type guard used in onDragEnd and overlay rendering to dispatch the correct handler 12 13

onDragEnd in VirtualizedRoomListView routes drops to either vm.changeSectionOrder(sourceId, targetId) or vm.changeRoomSection(sourceId, targetId) based on this guard 14.

Draggable and Droppable Components#

Room items — RoomListItemWrapper.tsx wraps each room in a DraggableWrapper (treegrid mode only) that calls useDraggable<RoomDragData> with two plugins:

• Feedback.configure({ feedback: "clone" }) — renders a floating clone rather than lifting the DOM element, preventing a hole in the virtualized list 15
• RestrictToVerticalAxis — limits movement to the vertical axis 16

Section headers — RoomListSectionHeaderView.tsx uses both useDraggable and useDroppable on each header:

• Dragging is gated on the canBeReordered flag — Favourites and Low Priority sections have this set to false and are pinned in place 17
• Dropping is enabled for all sections (rooms can be dropped on non-reorderable sections); it is only disabled for section-on-section drags targeting non-reorderable headers 18
• Visual indicators (.dropTargetTop, .dropTargetBottom) show whether the dragged section will land above or below the target 19
• On section drag start, all sections collapse so the user can see the full list; original states are restored on drop 3

Drag Overlay Strategy#

Both draggable types use Feedback.configure({ feedback: "clone" }) instead of lifting the actual DOM node. This is critical for virtualized lists — lifting the real element would leave a gap in the list. The floating clone is rendered in the <DragOverlay dropAnimation={null}> 20, which is positioned outside the virtual scroll container.

DragOverlayContent 21 calls useDragOperation to detect the active source and render:

• RoomListItemDragOverlayView — reuses RoomListItemContent with matching styles; hidden from the accessibility tree via aria-hidden since the real item stays in the DOM 22
• RoomListSectionHeaderDragOverlayView — reuses RoomListSectionHeaderContent; also aria-hidden 23

Accessibility#

A custom RoomListAccessibilityPlugin replaces dnd-kit's built-in Accessibility plugin. The reason: dnd-kit's default plugin sets aria-pressed/aria-grabbed on drag sources, which VoiceOver reads as "selected" — incorrect semantics 24.

The custom plugin maintains two aria-live regions 25:

• aria-live="polite" (role="status") — announces dragstart and dragover progress without interrupting speech
• aria-live="assertive" (role="alert") — announces the terminal dragend/cancel result, interrupting if necessary

Keyboard drag instructions are injected via a hidden element wired to each draggable's aria-describedby. The effect re-runs as draggables mount/unmount, supporting virtualized list scrolling 26.

All announcement strings are localized, including positional descriptions like "Section A will be moved before Section B" 3.

Version History#

The older matrix-react-sdk package used react-beautiful-dnd for the Space panel drag-and-drop 27. The new room list (element-web v2 architecture in shared-components) was built directly on @dnd-kit — there was no migration; @dnd-kit is the greenfield choice for the rewritten room list.

Key milestones:

The ^0.4.0 → ^0.5.0 upgrade also fixed a sensor bug where inline array sensor configs caused unnecessary entity mutations on every render 28.