A utility for creating a pan gesture that auto-selects items in a list, like your favorite gallery app.
- Supports Android & iOS
- Handles scrolling
- Super performant
- Headless API: Bring your own UI
- Works with typical scrollable views -
ScrollView,FlatList,FlashListetc.
Important
This package is in public alpha.
Feedback needed
If something is not working as it's supposed to, let me know by submitting an issue. I'm finalizing the initial API and on the lookout for edge cases before releasing v1.0.0
Important
This package requires Reanimated v3 and Gesture Handler v2.
npm install @osamaq/drag-selectyarn add @osamaq/drag-selectpnpm add @osamaq/drag-selectThis package is made with Reanimated & Gesture Handler, and using it requires some familiarity.
useDragSelect is a utility hook. It works by taking in parameters describing the UI of your list and returns managed gestures.
Paste this snippet into your project to get started.
import { useDragSelect } from "@osamaq/drag-select"
import { FlatList, View, Text } from "react-native"
import { GestureDetector } from "react-native-gesture-handler"
import Animated, { useAnimatedRef, useAnimatedScrollHandler } from "react-native-reanimated"
function List() {
const data = Array.from({ length: 50 }).map((_, index) => ({
id: `usr_${index}`,
name: "foo",
}))
const flatlist = useAnimatedRef<FlatList<(typeof data)[number]>>()
const { gestures, onScroll } = useDragSelect({
data,
key: "id",
list: {
animatedRef: flatlist,
numColumns: 2,
itemSize: { height: 50, width: 50 },
},
onItemSelected: (id, index) => {
console.log("onItemSelected", { id, index })
},
onItemDeselected: (id, index) => {
console.log("onItemDeselected", { id, index })
},
onItemPress: (id, index) => {
console.log("onItemPress", { id, index })
},
})
const scrollHandler = useAnimatedScrollHandler({ onScroll })
return (
<GestureDetector gesture={gestures.panHandler}>
<Animated.FlatList
data={data}
ref={flatlist}
numColumns={2}
onScroll={scrollHandler}
renderItem={({ item, index }) => (
<GestureDetector gesture={gestures.createItemPressHandler(item.id, index)}>
<View style={{ width: 50, height: 50, backgroundColor: "salmon" }}>
<Text>{item.id}</Text>
</View>
</GestureDetector>
)}
/>
</GestureDetector>
)
}Check out the step-by-step guide for more detailed instructions.
import { useDragSelect } from "@osamaq/drag-select"interface Config<ListItem = unknown> {
/**
* The same array of items rendered on screen in a scrollable view.
*/
data: Array<ListItem>
/**
* Key or path to nested key which uniquely identifies an item in the list.
* Nested key path is specified using dot notation in a string e.g. `"user.id"`.
*
* @example
* const item = { id: "usr_123", name: "foo" }
* useDragSelect({ key: "id" })
*/
key: PropertyPaths<ListItem>
list: {
/**
* An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef) to
* the scrollable view where the items are rendered.
*
* @example
* const animatedRef = useAnimatedRef()
* useDragSelect({ list: { animatedRef } })
* return <Animated.FlatList ref={animatedRef} />
*/
animatedRef: AnimatedRef<any>
/**
* Number of columns in the list.
* This only matters for vertical lists.
* @default 1
*/
numColumns?: number
/**
* Number of rows in the list.
* This only matters for horizontal lists.
* @default 1
*/
numRows?: number
/**
* Whether the list is horizontal.
* @default false
*/
horizontal?: boolean
/**
* Amount of horizontal space between rows.
* @default 0
*/
rowGap?: number
/**
* Amount of vertical space between columns.
* @default 0
*/
columnGap?: number
/**
* Height and width of each item in the list.
*/
itemSize: {
width: number
height: number
}
/**
* Inner distance between edges of the list and its items.
* Use this to account for list headers/footers and/or padding.
*/
contentInset?: {
top?: number
bottom?: number
left?: number
right?: number
}
}
/**
* Configuration for the long press gesture. Long pressing an item activates selection mode.
*/
longPressGesture?: {
/**
* Whether long pressing to activate selection mode is enabled.
* @default true
*/
enabled?: boolean
/**
* The amount of time in milliseconds an item must be pressed before selection mode activates.
* @default 300
*/
minDurationMs?: number
}
/**
* Configuration for automatic scrolling.
* This occurs when panning near scrolling edges of the list.
*/
panScrollGesture?: {
/**
* Whether automatic scrolling is enabled.
* @default true
*/
enabled?: boolean
/**
* How close should the pointer be to the start of the list before **inverse** scrolling begins.
* A value between 0 and 1 where 1 is equal to the height of the list window.
* @default 0.15
*/
startThreshold?: number
/**
* How close should the pointer be to the end of the list before scrolling begins.
* A value between 0 and 1 where 1 is equal to the height of the list window.
* @default 0.85
*/
endThreshold?: number
/**
* The maximum scrolling speed when the pointer is near the starting edge of the list window.
* Must be higher than 0.
* @default
* - 8 on iOS
* - 1 on Android
*/
startMaxVelocity?: number
/**
* The maximum scrolling speed when the pointer is at the ending edge of the list window.
* Must be higher than 0.
* @default
* - 8 on iOS
* - 1 on Android
*/
endMaxVelocity?: number
}
tapGesture?: {
/**
* Whether tapping an item while selection mode is active should add or remove it from selection.
* @default true
*/
selectOnTapEnabled: boolean
}
/**
* Invoked on the JS thread whenever an item is tapped, but not added to selection.
* You may still wrap items with your own pressable component while using this callback to handle the press event.
*/
onItemPress?: (id: string, index: number) => void
/**
* Invoked on the JS thread whenever an item is added to selection.
*/
onItemSelected?: (id: string, index: number) => void
/**
* Invoked on the JS thread whenever an item is removed from selection.
*/
onItemDeselected?: (id: string, index: number) => void
}interface DragSelect {
/**
* Must be used with [`useAnimatedScrollHandler`](https://docs.swmansion.com/react-native-reanimated/docs/scroll/useAnimatedScrollHandler)
* and passed to the animated list to use automatic scrolling.
* Used to obtain scroll offset and list window size.
*
* @example
* const { onScroll } = useDragSelect()
* const scrollHandler = useAnimatedScrollHandler(onScroll)
* return <Animated.FlatList onScroll={scrollHandler} />
*/
onScroll: (event: ReanimatedScrollEvent) => void
gestures: {
/**
* This returns a composed [tap](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture) and
* [long-press](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/long-press-gesture) gesture.
* Note that the long press gesture can be disabled by setting `config.longPressGesture.enabled` to `false`. See {@link Config.longPressGesture}.
*
* Do not customize the behavior of this gesture directly.
* Instead, [compose](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/composed-gestures) it with your own.
*/
createItemPressHandler: (id: string, index: number) => SimultaneousGesture
/**
* This is a single [pan gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture).
* If you need to rely solely on pressing items for selection, you can disable the pan gesture by setting `config.panScrollGesture.enabled` to `false`. See {@link Config.panScrollGesture}.
*
* Do not customize the behavior of this gesture directly.
* Instead, [compose](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/composed-gestures) it with your own.
*/
panHandler: PanGesture
}
selection: {
/**
* Whether the selection mode is active.
* Selection mode is active when there are any selected items.
*
* When active, tapping list items will add them or remove them from selection.
* Config callbacks {@link Config.onItemSelected} and {@link Config.onItemDeselected} will be invoked instead of {@link Config.onItemPress}.
*/
active: DerivedValue<boolean>
/**
* Add an item to selection.
*
* Must be invoked on the JS thread.
*/
add: (id: string) => void
/**
* Clear all selected items.
* Note that this does not trigger {@link Config.onItemDeselected}.
*
* Must be invoked on the JS thread.
*/
clear: () => void
/**
* Remove an item from selection.
*
* Must be invoked on the JS thread.
*/
delete: (id: string) => void
/**
* Indicates whether an item is selected.
*
* Must be invoked on the JS thread.
*/
has: (id: string) => boolean
/**
* Count of currently selected items.
*/
size: DerivedValue<number>
/**
* A mapping between selected item IDs and their indices.
*/
items: DerivedValue<Record<string, number>>
/**
* Counterpart API for the UI thread.
* Note that selection changes are reflected asynchronously on the JS thread and synchronously on the UI thread.
*/
ui: {
/**
* Add an item to selection.
*
* Must be invoked on the UI thread.
*/
add: (id: string) => void
/**
* Clear all selected items.
* Note that this does not trigger {@link Config.onItemDeselected}.
*
* Must be invoked on the UI thread.
*/
clear: () => void
/**
* Remove an item from selection.
*
* Must be invoked on the UI thread.
*/
delete: (id: string) => void
/**
* Indicates whether an item is selected.
*
* Must be invoked on the UI thread.
*/
has: (id: string) => boolean
}
}
}The recipes app contains sample integrations of drag-select.
| Sample | Remarks |
|---|---|
gallery_demo.mp4 |
Code Example of a FlatList integration.Has haptic feedback on selection change. |
file_manager_demo.mp4 |
Code Example of a ScrollView integration.List items are animated Pressable components. |
Running this utility is not inherently expensive. It works by doing some math on every frame update and only when panning the list. In my testing, I could not manage to get any frame drops at this point. However...
Performance cost comes from the additional logic added in response to changes in selection. You can easily cause frame drops by running expensive animations.
Tip
Try to be conservative in list item animations on selection change.
- Certain components and properties are more costly to animate than others
- Don't animate too many things at once
| Animations off | Animations on |
|---|---|
perf_ios_no_animations.mp4 |
perf_ios.mp4 |
Running on iPhone 12 mini in dev mode.
- Inverted lists
- Lists with dynamic item size
- Scroll view zoom
- Section lists
- Android, new architecture: In the new architecture, automatic scrolling will lead to the app hanging with an ANR notification. This appears to be a bug with React Native which is fixed in 0.77+
This project uses pnpm. You can install it here or through Corepack.
# install dependencies and start the dev app server
pnpm install
pnpm dev startConsider supporting the following projects:
- Reanimated, Gesture Handler
- This package would not be possible otherwise.
- create-react-native-library
- The CLI used for bootstrapping this project.