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)