feat: add per-item lock support to prevent dragging locked items

Author: ikiet

Example/navigation/index.tsx

@@ -12,11 +12,10 @@ import {
 } from "@react-navigation/native";
 import { createNativeStackNavigator } from "@react-navigation/native-stack";
 import * as React from "react";
-import { ColorSchemeName, Pressable } from "react-native";
+import { ColorSchemeName } from "react-native";
 
 import Colors from "../constants/Colors";
 import useColorScheme from "../hooks/useColorScheme";
-import NotFoundScreen from "../screens/NotFoundScreen";
 import BasicScreen from "../screens/BasicScreen";
 import SwipeableScreen from "../screens/SwipeableScreen";
 import {
@@ -27,6 +26,7 @@ import {
 import LinkingConfiguration from "./LinkingConfiguration";
 import NestedScreen from "../screens/NestedScreen";
 import HorizontalScreen from "../screens/HorizontalScreen";
+import LockedScreen from "../screens/LockedScreen";
 
 export default function Navigation({
   colorScheme,
@@ -113,6 +113,14 @@ function BottomTabNavigator() {
           ),
         }}
       />
+      <BottomTab.Screen
+        name="Locked"
+        component={LockedScreen}
+        options={{
+          title: "Locked",
+          tabBarIcon: ({ color }) => <TabBarIcon name="lock" color={color} />,
+        }}
+      />
     </BottomTab.Navigator>
   );
 }

Example/screens/LockedScreen.tsx

@@ -0,0 +1,80 @@
+import React, { useCallback, useState } from "react";
+import { Text, StyleSheet, TouchableOpacity } from "react-native";
+import DraggableFlatList, {
+  ScaleDecorator,
+  RenderItemParams,
+} from "react-native-draggable-flatlist";
+
+import { mapIndexToData } from "../utils";
+
+type Item = ReturnType<typeof mapIndexToData> & { locked: boolean };
+
+const NUM_ITEMS = 100;
+
+const initialData: Item[] = [...Array(NUM_ITEMS)].map((_, index, arr) => ({
+  ...mapIndexToData(_, index, arr),
+  locked: index % 4 === 0 && index !== 0,
+}));
+
+export default function LockedScreen() {
+  const [data, setData] = useState(initialData);
+
+  const renderItem = useCallback(
+    ({ item, drag, isActive, isLocked }: RenderItemParams<Item>) => {
+      return (
+        <ScaleDecorator>
+          <TouchableOpacity
+            activeOpacity={1}
+            onLongPress={drag}
+            disabled={isActive || isLocked}
+            style={[
+              styles.rowItem,
+              { backgroundColor: isActive ? "blue" : item.backgroundColor },
+              isLocked && styles.lockedItem,
+            ]}
+          >
+            <Text style={styles.text}>{item.text}</Text>
+            {isLocked && <Text style={styles.lockIcon}>🔒</Text>}
+          </TouchableOpacity>
+        </ScaleDecorator>
+      );
+    },
+    []
+  );
+
+  return (
+    <DraggableFlatList
+      data={data}
+      onDragEnd={({ data }) => setData(data)}
+      keyExtractor={(item) => item.key}
+      renderItem={renderItem}
+      isItemLocked={(item) => item.locked}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  rowItem: {
+    height: 100,
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+  },
+  lockedItem: {
+    opacity: 0.6,
+    height: 150,
+    borderWidth: 2,
+    borderColor: "rgba(255,255,255,0.5)",
+    borderStyle: "dashed",
+  },
+  text: {
+    color: "white",
+    fontSize: 24,
+    fontWeight: "bold",
+    textAlign: "center",
+  },
+  lockIcon: {
+    fontSize: 20,
+  },
+});

Example/tsconfig.json

@@ -1,6 +1,9 @@
 {
   "extends": "expo/tsconfig.base",
   "compilerOptions": {
-    "strict": true
+    "strict": true,
+    "paths": {
+      "react-native-draggable-flatlist": ["../src/index.tsx"]
+    }
   }
 }

Example/types.tsx

@@ -21,20 +21,19 @@ export type RootStackParamList = {
   NotFound: undefined;
 };
 
-export type RootStackScreenProps<
-  Screen extends keyof RootStackParamList
-> = NativeStackScreenProps<RootStackParamList, Screen>;
+export type RootStackScreenProps<Screen extends keyof RootStackParamList> =
+  NativeStackScreenProps<RootStackParamList, Screen>;
 
 export type RootTabParamList = {
   Basic: undefined;
   Nested: undefined;
   Swipeable: undefined;
   Horizontal: undefined;
+  Locked: undefined;
 };
 
-export type RootTabScreenProps<
-  Screen extends keyof RootTabParamList
-> = CompositeScreenProps<
-  BottomTabScreenProps<RootTabParamList, Screen>,
-  NativeStackScreenProps<RootStackParamList>
->;
+export type RootTabScreenProps<Screen extends keyof RootTabParamList> =
+  CompositeScreenProps<
+    BottomTabScreenProps<RootTabParamList, Screen>,
+    NativeStackScreenProps<RootStackParamList>
+  >;

README.md

@@ -35,7 +35,7 @@ All props are spread onto underlying [FlatList](https://facebook.github.io/react
 | :------------------------- | :---------------------------------------------------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 | `data`                     | `T[]`                                                                                     | Items to be rendered.                                                                                                                                                                                              |
 | `ref`                     | `React.RefObject<FlatList<T>>`                                                                                     | FlatList ref to be forwarded to the underlying FlatList.                                                                                                                                                                                      |
-| `renderItem`               | `(params: { item: T, getIndex: () => number \| undefined, drag: () => void, isActive: boolean}) => JSX.Element` | Call `drag` when the row should become active (i.e. in an `onLongPress` or `onPressIn`).                                                                                                                           |
+| `renderItem`               | `(params: { item: T, getIndex: () => number \| undefined, drag: () => void, isActive: boolean, isLocked: boolean}) => JSX.Element` | Call `drag` when the row should become active (i.e. in an `onLongPress` or `onPressIn`). `isLocked` is `true` when the item is locked via `isItemLocked`.                                                         |
 | `renderPlaceholder`        | `(params: { item: T, index: number }) => React.ReactNode`                                 | Component to be rendered underneath the hovering component                                                                                                                                                         |
 | `keyExtractor`             | `(item: T, index: number) => string`                                                      | Unique key for each item (required)                                                                                                                                                                                          |
 | `onDragBegin`              | `(index: number) => void`                                                                 | Called when row becomes active.                                                                                                                                                                                    |
@@ -49,6 +49,7 @@ All props are spread onto underlying [FlatList](https://facebook.github.io/react
 | `onPlaceholderIndexChange` | `(index: number) => void`                                                                 | Called when the index of the placeholder changes                                                                                                                                                                   |
 | `dragItemOverflow`         | `boolean`                                                                                 | If true, dragged item follows finger beyond list boundary.                                                                                                                                                         |
 | `dragHitSlop`              | `object: {top: number, left: number, bottom: number, right: number}`                      | Enables control over what part of the connected view area can be used to begin recognizing the gesture. Numbers need to be non-positive (only possible to reduce responsive area).                                 |
+| `isItemLocked`             | `(item: T, index: number) => boolean`                                                     | If returns `true` for an item, that item cannot be dragged and will not move when other items are dragged past it. Other items reorder around locked items, which maintain their absolute position in the array.   |
 | `debug`                    | `boolean`                                                                                 | Enables debug logging and animation debugger.                                                                                                                                                                      |
 | `containerStyle`           | `StyleProp<ViewStyle>`                                                                    | Style of the main component.                                                                                                                                                                                       |
 | `simultaneousHandlers`     | `React.Ref<any>` or `React.Ref<any>[]`                                                    | References to other gesture handlers, mainly useful when using this component within a `ScrollView`. See [Cross handler interactions](https://docs.swmansion.com/react-native-gesture-handler/docs/interactions/). |
@@ -59,6 +60,31 @@ All props are spread onto underlying [FlatList](https://facebook.github.io/react
 
 
 
+## Locked Items
+
+Use the `isItemLocked` prop to fix items in place. Locked items cannot be dragged and stay at their absolute position while other items reorder around them.
+
+```tsx
+<DraggableFlatList
+  data={data}
+  keyExtractor={(item) => item.id}
+  isItemLocked={(item) => item.fixed === true}
+  renderItem={({ item, drag, isActive, isLocked }) => (
+    <ScaleDecorator>
+      <TouchableOpacity
+        onLongPress={drag}
+        disabled={isActive || isLocked}
+        style={styles.rowItem}
+      >
+        <Text>{item.label}</Text>
+        {isLocked && <Text>📌</Text>}
+      </TouchableOpacity>
+    </ScaleDecorator>
+  )}
+  onDragEnd={({ data }) => setData(data)}
+/>
+```
+
 ## Cell Decorators
 
 Cell Decorators are an easy way to add common hover animations. For example, wrapping `renderItem` in the `<ScaleDecorator>` component will automatically scale up the active item while hovering (see example below).

src/components/CellRendererComponent.tsx

@@ -34,13 +34,9 @@ function CellRendererComponent<T>(props: Props<T>) {
   const viewRef = useRef<Animated.View>(null);
   const { cellDataRef, propsRef, containerRef } = useRefs<T>();
 
-  const { horizontalAnim, scrollOffset } = useAnimatedValues();
-  const {
-    activeKey,
-    keyExtractor,
-    horizontal,
-    layoutAnimationDisabled,
-  } = useDraggableFlatListContext<T>();
+  const { horizontalAnim, scrollOffset, cellSizesAnim } = useAnimatedValues();
+  const { activeKey, keyExtractor, horizontal, layoutAnimationDisabled } =
+    useDraggableFlatListContext<T>();
 
   const key = keyExtractor(item, index);
   const offset = useSharedValue(-1);
@@ -80,6 +76,12 @@ function CellRendererComponent<T>(props: Props<T>) {
 
       size.value = cellSize;
       offset.value = cellOffset;
+      runOnUI(() => {
+        "worklet";
+        const newSizes = [...cellSizesAnim.value];
+        newSizes[index] = cellSize;
+        cellSizesAnim.value = newSizes;
+      })();
     };
 
     const onFail = () => {
@@ -121,11 +123,8 @@ function CellRendererComponent<T>(props: Props<T>) {
     };
   }, [isActive, horizontal]);
 
-  const {
-    itemEnteringAnimation,
-    itemExitingAnimation,
-    itemLayoutAnimation,
-  } = propsRef.current;
+  const { itemEnteringAnimation, itemExitingAnimation, itemLayoutAnimation } =
+    propsRef.current;
 
   useEffect(() => {
     // NOTE: Keep an eye on reanimated LayoutAnimation refactor:

src/components/DraggableFlatList.tsx

@@ -52,9 +52,59 @@ type OnViewableItemsChangedCallback<T> = Exclude<
   undefined | null
 >;
 
-const AnimatedFlatList = (Animated.createAnimatedComponent(
+const AnimatedFlatList = Animated.createAnimatedComponent(
   FlatList
-) as unknown) as <T>(props: RNGHFlatListProps<T>) => React.ReactElement;
+) as unknown as <T>(props: RNGHFlatListProps<T>) => React.ReactElement;
+
+function reorderWithLockedItems<T>(
+  data: T[],
+  from: number,
+  to: number,
+  isItemLocked?: (item: T, index: number) => boolean
+): T[] {
+  if (from === to) return [...data];
+
+  if (!isItemLocked) {
+    const newData = [...data];
+    newData.splice(from, 1);
+    newData.splice(to, 0, data[from]);
+    return newData;
+  }
+
+  const lockedAt = new Map<number, T>();
+  data.forEach((item, i) => {
+    if (isItemLocked(item, i)) lockedAt.set(i, item);
+  });
+
+  const movable = data.filter((_, i) => !lockedAt.has(i));
+
+  let movableFrom = 0;
+  for (let i = 0; i < from; i++) {
+    if (!lockedAt.has(i)) movableFrom++;
+  }
+
+  let count = 0;
+  for (let i = 0; i < data.length; i++) {
+    if (i === from || lockedAt.has(i)) continue;
+    const gapIndex = i < from ? i : i - 1;
+    if (gapIndex < to) count++;
+  }
+  const movableTo = count;
+
+  const reordered = [...movable];
+  const [movedItem] = reordered.splice(movableFrom, 1);
+  reordered.splice(movableTo, 0, movedItem);
+
+  const result = new Array(data.length) as T[];
+  lockedAt.forEach((item, i) => {
+    result[i] = item;
+  });
+  let idx = 0;
+  for (let i = 0; i < result.length; i++) {
+    if (!lockedAt.has(i)) result[i] = reordered[idx++];
+  }
+  return result;
+}
 
 function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
   const {
@@ -82,6 +132,7 @@ function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
     viewableIndexMin,
     viewableIndexMax,
     disabled,
+    lockedIndicesAnim,
   } = useAnimatedValues();
 
   const reset = useStableCallback(() => {
@@ -96,7 +147,8 @@ function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
   const {
     dragHitSlop = DEFAULT_PROPS.dragHitSlop,
     scrollEnabled = DEFAULT_PROPS.scrollEnabled,
-    activationDistance: activationDistanceProp = DEFAULT_PROPS.activationDistance,
+    activationDistance:
+      activationDistanceProp = DEFAULT_PROPS.activationDistance,
   } = props;
 
   let [activeKey, setActiveKey] = useState<string | null>(null);
@@ -144,9 +196,22 @@ function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
     });
   }, [props.data, keyExtractor, keyToIndexRef]);
 
+  useLayoutEffect(() => {
+    const { isItemLocked, data } = propsRef.current;
+    lockedIndicesAnim.value = isItemLocked
+      ? data.map((item, index) => isItemLocked(item, index))
+      : [];
+  }, [props.data, props.isItemLocked]);
+
   const drag = useStableCallback((activeKey: string) => {
     if (disabled.value) return;
     const index = keyToIndexRef.current.get(activeKey);
+    if (
+      index !== undefined &&
+      propsRef.current.isItemLocked?.(propsRef.current.data[index], index)
+    ) {
+      return;
+    }
     const cellData = cellDataRef.current.get(activeKey);
     if (cellData) {
       activeCellOffset.value = cellData.measurements.offset;
@@ -200,18 +265,19 @@ function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
       if (index !== keyToIndexRef.current.get(key)) {
         keyToIndexRef.current.set(key, index);
       }
-
+      const isLocked = props.isItemLocked?.(item, index) ?? false;
       return (
         <RowItem
           item={item}
           itemKey={key}
           renderItem={props.renderItem}
           drag={drag}
           extraData={props.extraData}
+          isLocked={isLocked}
         />
       );
     },
-    [props.renderItem, props.extraData, drag, keyExtractor]
+    [props.renderItem, props.extraData, props.isItemLocked, drag, keyExtractor]
   );
 
   const onRelease = useStableCallback((index: number) => {
@@ -220,16 +286,9 @@ function DraggableFlatListInner<T>(props: DraggableFlatListProps<T>) {
 
   const onDragEnd = useStableCallback(
     ({ from, to }: { from: number; to: number }) => {
-      const { onDragEnd, data } = props;
-
-      const newData = [...data];
-      if (from !== to) {
-        newData.splice(from, 1);
-        newData.splice(to, 0, data[from]);
-      }
-
+      const { onDragEnd, data, isItemLocked } = props;
+      const newData = reorderWithLockedItems(data, from, to, isItemLocked);
       onDragEnd?.({ from, to, data: newData });
-
       setActiveKey(null);
     }
   );