Skip to content

README.md

Latest commit

 

History

History
515 lines (334 loc) · 12.7 KB

README.md

File metadata and controls

515 lines (334 loc) · 12.7 KB

React Native Reanimated DnD - Example App 📱

Interactive Examples Showcase

A comprehensive collection of 15 interactive examples demonstrating every feature of the React Native Reanimated DnD library.

React Native Expo TypeScript

🎯 Overview

This example app provides a hands-on demonstration of all the features available in the react-native-reanimated-dnd library. Each example is carefully crafted to showcase specific functionality, from basic drag-and-drop to advanced collision detection and custom animations.

🚀 Quick Start

Prerequisites

  • Node.js 20+
  • React Native development environment
  • iOS Simulator or Android Emulator (or physical device)

Installation & Setup

  1. Clone the repository:
git clone https://github.com/entropyconquers/react-native-reanimated-dnd.git
cd react-native-reanimated-dnd
  1. Install dependencies:
npm install
  1. Run the app:
# Development server
npm run start --workspace example-app

# iOS development build
npm run ios --workspace example-app

# Android development build
npm run android --workspace example-app

📚 Examples Catalog

🎵 Core Examples

Sortable Music Queue ♫

Perfect introduction to sortable lists

Features Demonstrated:

  • Reorderable vertical list with smooth animations
  • Drag handles for precise control
  • Auto-scrolling when dragging near edges
  • Real-time position updates and data synchronization
  • Long-press activation with haptic feedback

Key Components: Sortable, SortableItem, SortableItem.Handle

Use Cases: Music playlists, task lists, priority queues, menu reordering

Basic Drag & Drop 👆

Your first step into drag-and-drop

Features Demonstrated:

  • Simple draggable items with multiple drop zones
  • Visual feedback when hovering over drop zones
  • Basic data transfer between components
  • Clean, minimal implementation pattern

Key Components: Draggable, Droppable, DropProvider

Use Cases: File organization, category sorting, simple workflows

🔧 Interaction Examples

Drag Handles 🔧

Precise control over drag initiation

Features Demonstrated:

  • Handle-only dragging (rest of item non-draggable)
  • Mixed interaction patterns within single items
  • Custom handle styling and positioning
  • Accessibility considerations for touch targets

Key Components: Draggable.Handle

Use Cases: Complex UI cards, mixed-interaction lists, accessibility-focused designs

Drag State Management ⚡

Complete lifecycle state tracking

Features Demonstrated:

  • DraggableState enum usage (IDLE, DRAGGING, ANIMATING)
  • onStateChange callback implementation
  • Visual state indicators and conditional styling
  • State-based UI updates and animations

Key Components: State management hooks and callbacks

Use Cases: Complex UI feedback, analytics tracking, conditional behaviors

Dropped Items Map 📍

Real-time tracking of drop relationships

Features Demonstrated:

  • Track which draggables are on which droppables
  • Real-time mapping updates
  • Multi-zone state management
  • Persistent state across interactions

Key Components: Context state management

Use Cases: Kanban boards, inventory management, workspace organization

🎨 Visual & Animation Examples

Custom Animations 🎬

Bring your drag interactions to life

Features Demonstrated:

  • Custom timing functions with withTiming
  • Spring animations with withSpring
  • Easing variations (bezier, bounce, elastic)
  • Duration and damping controls
  • Chained and sequential animations

Key Components: Animation functions, animationFunction prop

Use Cases: Premium app experiences, game-like interactions, brand-specific animations

Active Drop Styles ✨

Beautiful visual feedback

Features Demonstrated:

  • Hover state styling with smooth transitions
  • Color changes and border effects
  • Scale transformations and shadow effects
  • Conditional styling based on drop state
  • CSS-like transition animations

Key Components: activeStyle prop, conditional styling

Use Cases: File upload zones, shopping carts, interactive dashboards

Alignment & Offset 📐

Pixel-perfect drop positioning

Features Demonstrated:

  • 9-point alignment system (top-left, center, bottom-right, etc.)
  • Custom offset values for fine-tuning
  • Visual alignment guides and indicators
  • Precise positioning control

Key Components: dropAlignment, dropOffset props

Use Cases: Layout builders, design tools, precise positioning requirements

🎯 Advanced Collision Examples

Collision Detection 🎯

Different strategies for drop detection

Features Demonstrated:

  • Center Algorithm: Precise center-point collision detection
  • Intersect Algorithm: Forgiving overlap detection (default)
  • Contain Algorithm: Strict containment requirement
  • Visual collision indicators and feedback
  • Performance implications of each algorithm

Key Components: collisionAlgorithm prop

Use Cases: Games, precise interactions, different UX requirements

Drop Zone Capacity 🗂️

Smart capacity management

Features Demonstrated:

  • Maximum item limits per drop zone
  • Visual capacity indicators (3/5 items)
  • Overflow handling and rejection
  • Dynamic capacity updates
  • Full/available state styling

Key Components: capacity prop, conditional logic

Use Cases: Limited slots, inventory systems, resource management

📦 Constraint Examples

Bounded Dragging 📦

Keep items within boundaries

Features Demonstrated:

  • Container-based boundary constraints
  • Visual boundary indicators
  • Smooth edge collision handling
  • Responsive boundary updates
  • Ref-based boundary definition

Key Components: dragBoundsRef prop

Use Cases: Canvas editors, constrained workspaces, mobile-friendly interactions

X-Axis Constraints ↔️

Horizontal-only movement

Features Demonstrated:

  • Horizontal slider implementations
  • Axis-locked dragging behavior
  • Custom constraint handling
  • Smooth horizontal motion
  • Value-based positioning

Key Components: dragAxis="x" prop

Use Cases: Sliders, horizontal timelines, progress controls

Y-Axis Constraints ↕️

Vertical-only movement

Features Demonstrated:

  • Vertical slider controls
  • Column-based movement patterns
  • Vertical constraint handling
  • Smooth vertical motion
  • List reordering patterns

Key Components: dragAxis="y" prop

Use Cases: Volume controls, vertical lists, priority ordering

Bounded Y-Axis 📏

Vertical movement with limits

Features Demonstrated:

  • Vertical movement within specific boundaries
  • Combined axis and boundary constraints
  • Boundary visualization
  • Smooth constraint handling
  • Range-based interactions

Key Components: dragAxis="y" + dragBoundsRef

Use Cases: Range selectors, bounded lists, constrained vertical controls

⚙️ Custom Implementation

Custom Draggable ⚙️

Advanced implementation patterns

Features Demonstrated:

  • Direct hook usage (useDraggable, useDroppable)
  • Advanced gesture handling patterns
  • Custom animation systems
  • Performance optimization techniques
  • Low-level API usage

Key Components: Core hooks and custom implementations

Use Cases: Highly customized interactions, performance-critical apps, unique UX patterns

🏗️ App Architecture

Navigation Structure

📱 App
├── 🏠 Home (Examples Navigation)
├── 🎵 Sortable Music Queue
├── 👆 Basic Drag & Drop
├── 🔧 Drag Handles
├── ⚡ Drag State Management
├── 📍 Dropped Items Map
├── 🎬 Custom Animations
├── ✨ Active Drop Styles
├── 📐 Alignment & Offset
├── 🎯 Collision Detection
├── 🗂️ Drop Zone Capacity
├── 📦 Bounded Dragging
├── ↔️ X-Axis Constraints
├── ↕️ Y-Axis Constraints
├── 📏 Bounded Y-Axis
└── ⚙️ Custom Draggable

Key Components

ExamplesNavigationPage

  • Beautiful home screen with example cards
  • Categorized example organization
  • Smooth navigation transitions
  • Custom fonts and styling

Example Components

  • Consistent header with back navigation
  • Interactive demonstrations
  • Real-time feedback and state display
  • Clean, educational code patterns

Shared Components

  • ExampleHeader - Consistent navigation
  • Footer - App information and links
  • BottomSheet - Settings and options

🎨 Design System

Typography

  • Primary Font: Major Mono Display (headers)
  • Body Font: Kumbh Sans (content)
  • Weights: Regular, Medium, SemiBold, Bold

Color Palette

  • Background: Deep black (#000000)
  • Cards: Dark gray with subtle borders
  • Accent: Red highlights for branding
  • Text: High contrast white/gray
  • Interactive: Blue and green for actions

Animations

  • Duration: 300ms standard, 200ms quick
  • Easing: Smooth bezier curves
  • Spring: Natural physics-based motion
  • Feedback: Haptic feedback on interactions

🔧 Technical Implementation

Dependencies

{
  "react-native-reanimated": "^3.5.0",
  "react-native-gesture-handler": "^2.13.0",
  "@react-navigation/native": "^6.1.0",
  "@react-navigation/stack": "^6.3.0",
  "expo": "~49.0.0"
}

Performance Optimizations

  • Worklet Functions: All animations run on UI thread
  • Gesture Handler: Native gesture recognition
  • Reanimated 3: Latest performance improvements
  • Memoization: Optimized re-renders
  • Lazy Loading: Efficient navigation

Code Organization

📁 example-app/
├── 📁 components/
│   ├── 📁 examples/          # All example implementations
│   ├── ExamplesNavigationPage.tsx
│   ├── ExampleHeader.tsx
│   └── Footer.tsx
├── 📁 navigation/
│   └── AppNavigator.tsx      # React Navigation setup
├── 📁 assets/               # Images and fonts
└── App.tsx                  # Root component

🎯 Learning Path

Beginner

  1. Basic Drag & Drop - Understand core concepts
  2. Sortable Music Queue - Learn list reordering
  3. Active Drop Styles - Add visual feedback

Intermediate

  1. Drag Handles - Implement precise controls
  2. Collision Detection - Understand algorithms
  3. Bounded Dragging - Add constraints
  4. Custom Animations - Enhance user experience

Advanced

  1. Drag State Management - Master state tracking
  2. Dropped Items Map - Complex state management
  3. Alignment & Offset - Precise positioning
  4. Capacity Management - Smart limitations
  5. Axis Constraints - Specialized interactions
  6. Custom Implementation - Build from scratch

🤝 Contributing to Examples

We welcome contributions to improve and expand the example collection!

Adding New Examples

  1. Create new component in components/examples/
  2. Add to navigation in AppNavigator.tsx
  3. Update ExamplesNavigationPage.tsx
  4. Follow existing patterns and styling

Improving Existing Examples

  1. Enhance visual design
  2. Add more interactive features
  3. Improve code comments and documentation
  4. Optimize performance

📱 Device Testing

Recommended Testing

  • iOS: iPhone 12+ (iOS 14+)
  • Android: API 21+ (Android 5.0+)
  • Tablets: iPad, Android tablets
  • Physical Devices: Best performance testing

Performance Notes

  • Animations run at 60fps on modern devices
  • Gesture recognition is native and responsive
  • Memory usage is optimized for mobile
  • Works well on both platforms

🔗 Related Resources

🎯 Ready to explore drag-and-drop interactions?

Run the app and start with the Basic Drag & Drop example!

📱 Run the App • 📖 View Source • ⭐ Star on GitHub