Drag-and-Drop & Sortable Interfaces Purpose
This skill helps implement drag-and-drop interactions and sortable interfaces using modern React/TypeScript libraries. It covers accessibility-first approaches, touch support, and performance optimization for creating intuitive direct manipulation UIs.
When to Use
Invoke this skill when:
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
Reference references/dnd-patterns.md for:
Vertical lists with drag handles Horizontal lists for tab/carousel reordering Grid layouts with 2D dragging Auto-scrolling near edges Kanban Boards
Reference references/kanban-implementation.md for:
Multi-column boards with cards WIP limits and swimlanes Card preview on hover Column management (add/remove/collapse) File Upload Zones
Reference references/file-dropzone.md for:
Visual feedback states File type validation Multi-file handling Progress indicators Accessibility
Reference references/accessibility-dnd.md for:
Keyboard navigation patterns Screen reader announcements Alternative UI approaches ARIA attributes Library Selection Primary: dnd-kit
Modern, accessible, and performant drag-and-drop for React.
Reference references/library-guide.md for:
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
Determine the drag-and-drop pattern needed:
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
Install required packages:
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
Step 3: Implement Core Functionality
Use examples as starting points:
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
Reference references/accessibility-dnd.md to:
Implement keyboard navigation Add screen reader announcements Provide alternative controls Test with assistive technologies
Run scripts/validate_accessibility.js to check implementation.
Step 5: Optimize Performance
For lists with >100 items:
Reference references/performance-optimization.md Implement virtual scrolling Use scripts/calculate_drop_position.js for efficient calculations Step 6: Style with Design Tokens
Apply theming using the design-tokens skill:
Reference design token variables Implement drag states (hovering, dragging, dropping) Add visual feedback and animations Mobile & Touch Support
Reference references/touch-support.md for:
Long press to initiate drag Preventing scroll during drag Touch-friendly hit areas (44px minimum) Gesture conflict resolution State Management
Reference references/state-management.md for:
Managing drag state in React Optimistic updates Undo/redo functionality Persisting order changes Scripts Calculate Drop Position
Run scripts/calculate_drop_position.js to:
Determine valid drop zones Calculate insertion indices Handle edge cases Generate Configuration
Run scripts/generate_dnd_config.js to:
Create dnd-kit configuration Set up sensors and modifiers Configure animations Validate Accessibility
Run scripts/validate_accessibility.js to:
Check keyboard navigation Verify ARIA attributes Test screen reader compatibility Examples
Each example includes complete TypeScript code with accessibility:
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 provides:
Type definitions for drag state Event handler types Configuration interfaces Configuration Schema
assets/dnd-config-schema.json defines:
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
Reference the appropriate guide for each issue:
Accessibility → references/accessibility-dnd.md Touch → references/touch-support.md Performance → references/performance-optimization.md State → references/state-management.md Testing Checklist
Before deployment, verify:
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
After implementing basic drag-and-drop:
Add advanced features (auto-scroll, multi-select) Implement gesture support for mobile Add animation polish with Framer Motion Create custom drag preview components Build complex interactions (nested dragging)