Drag-and-Drop & Sortable Interfaces

Purpose

When to Use

• Building Trello-style kanban boards with draggable cards between columns
• Creating sortable lists with drag handles for priority ordering
• Implementing file upload zones with visual drag-and-drop feedback
• Building reorderable grids for dashboard widgets or galleries
• Creating visual builders with node-based interfaces
• Implementing any UI requiring spatial reorganization through direct manipulation

Core Patterns

Sortable Lists

references/dnd-patterns.md

• Vertical lists with drag handles
• Horizontal lists for tab/carousel reordering
• Grid layouts with 2D dragging
• Auto-scrolling near edges

Kanban Boards

references/kanban-implementation.md

• Multi-column boards with cards
• WIP limits and swimlanes
• Card preview on hover
• Column management (add/remove/collapse)

File Upload Zones

references/file-dropzone.md

• Visual feedback states
• File type validation
• Multi-file handling
• Progress indicators

Accessibility

references/accessibility-dnd.md

• Keyboard navigation patterns
• Screen reader announcements
• Alternative UI approaches
• ARIA attributes

Library Selection

Primary: dnd-kit

references/library-guide.md

• Library comparison (dnd-kit vs alternatives)
• Installation and setup
• Core concepts and API
• Migration from react-beautiful-dnd

Key Features

• Built-in accessibility support
• Touch, mouse, and keyboard input
• Zero dependencies (~10KB core)
• Highly customizable
• TypeScript native

Implementation Workflow

Step 1: Analyze Requirements

• Simple list reordering → Sortable list pattern
• Multi-container movement → Kanban pattern
• File handling → Dropzone pattern
• Complex interactions → Visual builder pattern

Step 2: Set Up Library

npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

Step 3: Implement Core Functionality

• examples/sortable-list.tsx

  for basic lists

• examples/kanban-board.tsx

  for multi-column boards

• examples/file-dropzone.tsx

  for file uploads

• examples/grid-reorder.tsx

  for grid layouts

Step 4: Add Accessibility

references/accessibility-dnd.md

• Implement keyboard navigation
• Add screen reader announcements
• Provide alternative controls
• Test with assistive technologies

scripts/validate_accessibility.js

Step 5: Optimize Performance

• Reference

  references/performance-optimization.md

• Implement virtual scrolling
• Use

  scripts/calculate_drop_position.js

  for efficient calculations

Step 6: Style with Design Tokens

• Reference design token variables
• Implement drag states (hovering, dragging, dropping)
• Add visual feedback and animations

Mobile & Touch Support

references/touch-support.md

• Long press to initiate drag
• Preventing scroll during drag
• Touch-friendly hit areas (44px minimum)
• Gesture conflict resolution

State Management

references/state-management.md

• Managing drag state in React
• Optimistic updates
• Undo/redo functionality
• Persisting order changes

Scripts

Calculate Drop Position

scripts/calculate_drop_position.js

• Determine valid drop zones
• Calculate insertion indices
• Handle edge cases

Generate Configuration

scripts/generate_dnd_config.js

• Create dnd-kit configuration
• Set up sensors and modifiers
• Configure animations

Validate Accessibility

scripts/validate_accessibility.js

• Check keyboard navigation
• Verify ARIA attributes
• Test screen reader compatibility

Examples

Sortable List

examples/sortable-list.tsx

• Vertical list with drag handles
• Keyboard navigation (Space/Enter to grab, arrows to move)
• Screen reader announcements

Kanban Board

examples/kanban-board.tsx

• Multiple columns with draggable cards
• Card movement between columns
• Column management features
• WIP limits

File Dropzone

examples/file-dropzone.tsx

• Drag files to upload
• Visual feedback states
• File type validation
• Upload progress

Grid Reorder

examples/grid-reorder.tsx

• 2D grid dragging
• Auto-layout on drop
• Responsive breakpoints

Assets

TypeScript Types

assets/drag-state-types.ts

• Type definitions for drag state
• Event handler types
• Configuration interfaces

Configuration Schema

assets/dnd-config-schema.json

• Valid configuration options
• Sensor settings
• Animation parameters

Best Practices

Visual Feedback

• Show drag handles (⋮⋮) to indicate draggability
• Change cursor (grab → grabbing)
• Display drop zone placeholders
• Make dragged items semi-transparent
• Highlight valid drop targets

Performance

• Use CSS transforms, not position properties
• Apply

  will-change: transform

  for animations
• Throttle drag events for large lists
• Implement virtual scrolling when needed

Accessibility First

• Always provide keyboard alternatives
• Include screen reader announcements
• Test with NVDA/JAWS/VoiceOver
• Provide non-drag alternatives (buttons/forms)

Error Handling

• Show invalid drop feedback
• Implement undo functionality
• Auto-save after successful drops
• Handle network failures gracefully

Common Pitfalls

Avoid These Issues

• Forgetting keyboard navigation
• Missing touch support
• Not preventing scroll during drag
• Ignoring accessibility
• Poor performance with large lists

Solutions

• Accessibility →

  references/accessibility-dnd.md

• Touch →

  references/touch-support.md

• Performance →

  references/performance-optimization.md

• State →

  references/state-management.md

Testing Checklist

• Keyboard navigation works completely
• Screen readers announce all actions
• Touch devices can drag smoothly
• Performance acceptable with expected data volume
• Visual feedback clear and responsive
• Undo/redo functionality works
• Alternative UI provided for accessibility
• Works across all target browsers

Next Steps

1. Add advanced features (auto-scroll, multi-select)
2. Implement gesture support for mobile
3. Add animation polish with Framer Motion
4. Create custom drag preview components
5. Build complex interactions (nested dragging)