Implements drag-and-drop and sortable interfaces with React/TypeScript including kanban boards, sortable lists, file uploads, and reorderable grids. Use when building interactive UIs requiring direct manipulation, spatial organization, or touch-friendly reordering.
apm install @ancoleman/implementing-drag-drop[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@ancoleman/implementing-drag-drop)---
name: implementing-drag-drop
description: Implements drag-and-drop and sortable interfaces with React/TypeScript including kanban boards, sortable lists, file uploads, and reorderable grids. Use when building interactive UIs requiring direct manipulation, spatial organization, or touch-friendly reordering.
---
# 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:
```bash
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:
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)