# react-native-drax [![React Native CLI](https://img.shields.io/badge/-React%20Native%20CLI-282C34?style=flat-square&logo=react&logoColor=61DAFB)](https://reactnative.dev/) [![Expo CLI](https://img.shields.io/badge/-Expo%20CLI-282C34?style=flat-square&logo=expo&logoColor=white)](https://expo.dev/) [![platforms](https://img.shields.io/badge/platforms-Android%20%7C%20iOS%20%7C%20Web-brightgreen.svg?style=flat-square&colorB=191A17)](https://necolas.github.io/react-native-web/) [![GitHub top language](https://img.shields.io/github/languages/top/nuclearpasta/react-native-drax?style=flat-square)](https://github.com/nuclearpasta/react-native-drax/search?l=typescript) [![CI](https://github.com/nuclearpasta/react-native-drax/actions/workflows/ci.yml/badge.svg)](https://github.com/nuclearpasta/react-native-drax/actions/workflows/ci.yml) [![GitHub license](https://img.shields.io/github/license/nuclearpasta/react-native-drax?style=flat-square)](https://github.com/nuclearpasta/react-native-drax/blob/main/LICENSE.md) [![npm version](https://img.shields.io/npm/v/react-native-drax?style=flat-square)](https://www.npmjs.com/package/react-native-drax) ๐Ÿ“š [**Visit the official documentation**](https://nuclearpasta.com/react-native-drax) ๐ŸŽฎ [**See the live example**](https://nuclearpasta.com/react-native-drax/example) ## ๐Ÿ“– Overview Drax is a declarative drag-and-drop framework for React Native, written in TypeScript. It supports free-form drag-and-drop, sortable lists and grids, cross-list reorder, drag handles, collision algorithms, and more. Built on [Reanimated 4](https://docs.swmansion.com/react-native-reanimated/) and [Gesture Handler 3](https://docs.swmansion.com/react-native-gesture-handler/) with a UI-thread-first architecture for smooth 60fps interactions. **Platforms:** iOS, Android, Web ### โœจ Highlights - ๐Ÿ“‹ **List-agnostic sortable** โ€” works with FlatList, FlashList, LegendList, or any list component - ๐Ÿ”€ **Cross-container drag** โ€” move items between lists (cross-list reorder) - โšก **UI-thread hit-testing** โ€” spatial index worklet for fast receiver detection - โœŠ **Drag handles** โ€” only the handle starts a drag, the rest scrolls - ๐Ÿ’ฅ **Collision algorithms** โ€” center, intersect, or contain - ๐Ÿ“ **Drag bounds** โ€” constrain drags within a view - ๐ŸŽจ **Hover styles** โ€” conditional styles based on drag phase and receiver state - ๐Ÿšซ **Drop zone acceptance** โ€” accept or reject drops with `acceptsDrag` - ๐ŸŽฌ **Animation presets** โ€” default, spring, gentle, snappy, none โ€” or custom config - ๐Ÿงฒ **Snap alignment** โ€” snap to 9-point alignment within receivers - โ™ฟ **Accessibility** โ€” auto-generated labels, reduced motion support - ๐Ÿ“ก **19 callback events** โ€” full drag lifecycle control - ๐Ÿ—๏ธ **New Architecture** compatible (Fabric) ### ๐Ÿค” Why Drax? | Feature | Drax | reanimated-dnd | sortables | |---|:---:|:---:|:---:| | Free-form drag & drop | โœ… | โœ… | โž– | | Sortable list / grid | โœ… | โœ… | โœ… | | Mixed-size grid (non-uniform spans) | โœ… | โž– | โž– | | Cross-container / cross-list reorder | โš ๏ธ Experimental | โž– | โž– | | List-agnostic (FlatList, FlashList, LegendList) | โœ… | โž– | โž– | | Drag handles | โœ… | โœ… | โœ… | | Drag state styling | 15 props + inactive | onStateChange | 5 props + hook | | Drop indicator | โœ… | โž– | Grid only | | UI-thread DnD collision | โœ… | โž– | โž– | | Event callbacks | 19 types | ~12 types | ~10 types | | Accessibility + reduced motion | โœ… | Manual | Manual | | Web support | โœ… | โž– | Partial | | Reanimated | โ‰ฅ 4 | โ‰ฅ 4.2 | โ‰ฅ 3 | | Gesture Handler | โ‰ฅ 2 | โ‰ฅ 2.28 | โ‰ฅ 2 | [See full comparison โ†’](https://nuclearpasta.com/react-native-drax#comparison) ## ๐Ÿ“ฆ Installation ```bash npm install react-native-drax # or yarn add react-native-drax ``` ### ๐Ÿ”— Peer Dependencies ```bash npm install react-native-reanimated react-native-gesture-handler ``` | Peer Dependency | Version | |---|---| | `react` | >= 18 | | `react-native` | >= 0.68 | | `react-native-reanimated` | ^4.0.0 | | `react-native-gesture-handler` | >= 2.0.0 (v3 recommended) | ## ๐Ÿš€ Quick Start ### ๐Ÿ‘‹ Basic Drag-and-Drop ```tsx import { DraxProvider, DraxView } from 'react-native-drax'; function App() { return ( console.log('dragging')} payload="hello" /> { console.log(`received: ${payload}`); }} /> ); } ``` ### ๐Ÿ“‹ Sortable List The simplest way to make a reorderable list: ```tsx import { useState } from 'react'; import { Text, View } from 'react-native'; import { DraxProvider, DraxList } from 'react-native-drax'; function App() { const [items, setItems] = useState(['A', 'B', 'C', 'D', 'E']); return ( item} onReorder={({ data }) => setItems(data)} renderItem={({ item }) => ( {item} )} /> ); } ``` `DraxList` is list-agnostic โ€” pass any list component via the `component` prop: ```tsx import { FlashList } from '@shopify/flash-list'; item.id} onReorder={({ data }) => setItems(data)} renderItem={({ item }) => } estimatedItemSize={60} /> ``` ### ๐Ÿงฑ Composable API For full control, use the composable primitives directly: ```tsx import { DraxProvider, useSortableList, SortableContainer, SortableItem, } from 'react-native-drax'; import { FlatList } from 'react-native'; function App() { const [items, setItems] = useState(['A', 'B', 'C', 'D', 'E']); const listRef = useRef(null); const sortable = useSortableList({ data: items, keyExtractor: (item) => item, onReorder: ({ data }) => setItems(data), }); return ( ( {item} )} /> ); } ``` This pattern works with any list component โ€” FlatList, FlashList, LegendList, ScrollView, etc. ## ๐ŸŽ› Features ### โœŠ Drag Handles Only the handle area starts a drag โ€” the rest of the view scrolls normally: ```tsx import { DraxView, DraxHandle } from 'react-native-drax'; This content scrolls normally {/* Only this starts a drag */} ``` ### ๐Ÿ“ Drag Bounds Constrain a dragged view within a boundary: ```tsx const boundsRef = useRef(null); I can only be dragged within the parent ``` ### ๐Ÿ’ฅ Collision Algorithms Control how receiver detection works: ```tsx {/* hover center inside receiver (default) */} {/* any overlap triggers receiving */} {/* dragged view must be fully inside */} ``` ### ๐Ÿšซ Drop Zone Acceptance Accept or reject drops conditionally: ```tsx items.length < 5} onReceiveDragDrop={({ dragged }) => addItem(dragged.payload)} /> ``` ### ๐ŸŽจ Hover Styles Style the hover layer based on drag state: ```tsx ``` ### ๐Ÿงฒ Snap Alignment Snap dropped items to specific positions within a receiver: ```tsx import { snapToAlignment } from 'react-native-drax'; snapToAlignment(receiver, dragged, 'top-left', { x: 8, y: 8 }) } /> ``` Alignments: `center`, `top-left`, `top-center`, `top-right`, `center-left`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right` ### ๐ŸŽฌ Animation Presets ```tsx {/* spring physics */} {/* soft spring */} {/* fast spring */} {/* instant */} {/* Or custom: */} ``` Device reduced motion settings are respected automatically. ### ๐Ÿ“ก Continuous Drag Callbacks ```tsx { /* fires every frame while dragging over empty space */ }} onDragOver={(data) => { /* fires every frame while over the same receiver */ }} /> ``` ### ๐Ÿ”€ Cross-Container Sortable (Experimental) Move items between lists (cross-list reorder): ```tsx import { useSortableBoard, SortableBoardContainer, useSortableList, SortableContainer, SortableItem, } from 'react-native-drax'; const board = useSortableBoard({ onTransfer: ({ fromColumnId, toColumnId, fromIndex, toIndex, item }) => { // Move item between columns }, }); {columns.map((column) => ( ))} ``` > **Note:** Cross-container drag is experimental. The API may change in future versions. ### ๐Ÿท๏ธ Namespace API For convenience, all components are available under the `Drax` namespace: ```tsx import { Drax } from 'react-native-drax'; ``` ## ๐Ÿงฉ Components | Component | Description | |---|---| | `DraxProvider` | Context provider โ€” wrap your app's drag-and-drop area | | `DraxView` | Draggable and/or receptive view with 19 callback events | | `DraxList` | List-agnostic sortable list (convenience wrapper) | | `DraxHandle` | Drag handle โ€” only this area starts a drag | | `DraxScrollView` | Scrollable container with auto-scroll during drag | | `SortableContainer` | Monitoring wrapper for composable sortable API | | `SortableItem` | Per-item wrapper with shift animation | | `SortableBoardContainer` | Cross-container board coordinator (experimental) | ## ๐Ÿช Hooks | Hook | Description | |---|---| | `useSortableList` | List-agnostic reorder state management | | `useSortableBoard` | Cross-container board coordinator (experimental) | | `useDraxContext` | Access the Drax context | | `useDraxId` | Generate a unique Drax view ID | ## ๐Ÿ’ก Examples The `example/` directory contains an Expo Router app with 11 screens demonstrating all features: | Screen | Features shown | |---|---| | Color Drag & Drop | Drop acceptance, hover styles, snap alignment | | Reorderable List | DraxList, animation presets, auto-scroll | | Reorderable Grid | Sortable grid with multi-column layout | | Mixed-Size Grid | Items with different spans (1ร—1, 2ร—2, etc.) using `getItemSpan` and `packGrid` | | Drag Handles | Only the grip icon starts a drag | | Drag Bounds | Constrain drag within a view | | Collision Modes | Center vs Intersect vs Contain | | Cross-List Reorder | FlashList + LegendList + FlatList cross-container drag (experimental) | | Knight Moves | Chess knight drag puzzle | | Scrolling | Drag from scroll view to drop zone | | Stress Test | 100 items in a sortable list | To run the example app: ```bash cd example && yarn start ``` ## ๐Ÿ”„ Migration from v0.x v1.0.0 is a complete rewrite. Key changes: - **`DraxList` is new** โ€” list-agnostic convenience wrapper using the new sortable architecture. The old `DraxList` / `DraxListItem` API from v0.10.x and v0.11.0-alpha is removed. - **New sortable architecture** โ€” `useSortableList` + `SortableContainer` + `SortableItem` composable API replaces the old array-indexed approach. - **Reanimated 4 + Gesture Handler 3** โ€” required peer dependencies (Gesture Handler v2 supported via compat layer with reduced performance). - **New Architecture (Fabric)** compatible. ## ๐Ÿ“‹ Changelog See [CHANGELOG.md](CHANGELOG.md) for a full list of changes. ## ๐Ÿค Contributing Issues, pull requests, and discussion are all welcome. See the [Contribution Guidelines](CONTRIBUTING.md) for details. ## ๐Ÿ“œ Code of Conduct This project is released with a [Contributor Code of Conduct](CODE-OF-CONDUCT.md). By participating in this project you agree to abide by its terms. ## ๐Ÿ† Contributors Originally created by [Joe Lafiosca](https://github.com/lafiosca). v1.0.0 rewrite led by [Ovidiu Cristescu](https://github.com/LunatiqueCoder). Thanks to all contributors who have helped make Drax better:
Joe Lafiosca
Joe Lafiosca
๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿšง ๐Ÿš‡		 Ovidiu Cristescu
Ovidiu Cristescu
๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿšง		 Franรงois Dupayrat
Franรงois Dupayrat
๐Ÿ’ป		 Josh Arnold
Josh Arnold
๐Ÿ’ป		 Rahul Nallappa
Rahul Nallappa
๐Ÿ’ป		 negue
negue
๐Ÿ“–		 Chris Drackett
Chris Drackett
๐Ÿ’ป
Matti Salokangas
Matti Salokangas
๐Ÿ’ป		 Andres Garcia
Andres Garcia
๐Ÿ’ป
## ๐Ÿ“ƒ License [MIT](LICENSE.md) --- Built and maintained using [OpenKit](https://www.openkit.work/).