react-native-reorderable-list v0.12.0

React Native Reorderable List

A reorderable list for React Native applications, powered by Reanimated 🚀

Index

• Install
• Components
  • ReorderableList
  • ScrollViewContainer
  • NestedReorderableList
• Hooks
  • useReorderableDrag
  • useReorderableDragStart
  • useReorderableDragEnd
  • useIsActive
• Utils
• Troubleshooting
  • RefreshControl
• Example
• License

Install

NOTE: This package follows semantic versioning. Versions 0.X.0 are safe to use but may introduce breaking changes, as the public API is not considered stable yet.

Npm:

npm install --save react-native-reorderable-list

Yarn:

yarn add react-native-reorderable-list

Then you need to install these two peer dependencies:

• React Native Reanimated >=3.12.0
• React Native Gesture Handler >=2.12.0

Components

ReorderableList

This component uses a FlatList and it extends its props:

The following props from FlatList are not supported:

• horizontal
• scrollEventThrottle
• removeClippedSubviews
• CellRendererComponent
• numColumns

ScrollViewContainer

This component extends the ScrollView component and is used for nesting a NestedReorderableList within a scrollable container:

NestedReorderableList

This component allows nesting a reorderable list within a ScrollViewContainer:

Hooks

useReorderableDrag

This hook creates a function that triggers the drag of a list item. It's usually called on a long press event. This hook can only be used inside of a list item component.

Returns

• () => void

useReorderableDragStart

This hook allows handling the drag start event of a list item. This hook can only be used inside of a list item component. It receives a worklet callback that is called when the drag starts. It's recommended to wrap the handler function in a useCallback as follows:

useReorderableDragStart(
  useCallback((index: number) => {
    'worklet';

    // ...
  }, []),
);

Using this hook in large lists is discouraged due to performance bottlenecks, prefer onDragStart on the ReorderableList instead.

useReorderableDragEnd

This hook allows handling the drag end event of a list item. This hook can only be used inside of a list item component. It receives a worklet callback that is called when the drag starts. It's recommended to wrap the handler function in a useCallback as follows:

useReorderableDragEnd(
  useCallback((from: number, to: number) => {
    'worklet';

    // ...
  }, []),
);

Using this hook in large lists is discouraged due to performance bottlenecks, prefer onDragEnd on the ReorderableList instead.

useIsActive

This hook returns a boolean indicating whether the current item is active. It will return true on drag start and false on drag end. This hook can only be used inside of a list item component.

const isActive = useIsActive();

Additionally this hook requires setting shouldUpdateActiveItem to true on the ReorderableList:

<ReorderableList
  // ...
  shouldUpdateActiveItem
/>

Utils

• reorderItems: <T>(data: T[], from: number, to: number) => T[]

  This function receives an array of items, the index of the item to be moved, and the index of the new position and it returns a new array with the items reordered.

Troubleshooting

RefreshControl

If you want to use RefreshControl with ReorderableList you might encounter some issues on Android, where gestures are conflicting making one or both of the components non responsive. To overcome this issues you can delay the activation of pan gestures necessary for dragging items by using the panActivateAfterLongPress prop. This duration should be slightly longer than the long press delay necessary to drag your items. If you're using Pressable the delayLongPress is 500 ms by default.

<ReorderableList
  // ...
  panActivateAfterLongPress={Platform.OS === 'android' ? 520 : undefined}
/>

If you change delayLongPress on your Pressable, update this prop accordingly.

Another issue you'll encounter is that when you drag your items the RefreshControl might animate. To avoid this you can enable and disable it on drag start and drag end like so:

const [refreshEnabled, setRefreshEnabled] = useState(true);

const handleDragStart = useCallback(() => {
  'worklet';

  // NOTE: If it's refreshing we don't want the refresh control to disappear
  // and we can keep it enabled since it won't conflict with the drag.
  if (Platform.OS === 'android' && !refreshing) {
    runOnJS(setRefreshEnabled)(false);
  }
}, [refreshing]);

const handleDragEnd = useCallback(() => {
  'worklet';

  if (Platform.OS === 'android') {
    runOnJS(setRefreshEnabled)(true);
  }
}, []);

return (
  <ReorderableList
    // ...
    onDragStart={handleDragStart}
    onDragEnd={handleDragEnd}
    refreshControl={
      <RefreshControl
        // ...
        enabled={refreshEnabled}
      />
    }
  />
);

Example

Here is simple example of how to use this component. Examples of nested lists and much more can be found in the example directory.

import React, {memo, useState} from 'react';
import {ListRenderItemInfo, Pressable, StyleSheet, Text} from 'react-native';

import ReorderableList, {
  ReorderableListReorderEvent,
  reorderItems,
  useReorderableDrag,
} from 'react-native-reorderable-list';

interface CardProps {
  id: string;
  color: string;
  height: number;
}

const rand = () => Math.floor(Math.random() * 256);

const seedData: CardProps[] = Array(20)
  .fill(null)
  .map((_, i) => ({
    id: i.toString(),
    color: `rgb(${rand()}, ${rand()}, ${rand()})`,
    height: Math.max(60, Math.floor(Math.random() * 100)),
  }));

const Card: React.FC<CardProps> = memo(({id, color, height}) => {
  const drag = useReorderableDrag();

  return (
    <Pressable style={[styles.card, {height}]} onLongPress={drag}>
      <Text style={[styles.text, {color}]}>Card {id}</Text>
    </Pressable>
  );
});

const Example = () => {
  const [data, setData] = useState(seedData);

  const handleReorder = ({from, to}: ReorderableListReorderEvent) => {
    setData(value => reorderItems(value, from, to));
  };

  const renderItem = ({item}: ListRenderItemInfo<CardProps>) => (
    <Card {...item} />
  );

  return (
    <ReorderableList
      data={data}
      onReorder={handleReorder}
      renderItem={renderItem}
      keyExtractor={item => item.id}
    />
  );
};

const styles = StyleSheet.create({
  card: {
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: 'white',
    borderBottomWidth: 1,
    borderBottomColor: '#ddd',
  },
  text: {
    fontSize: 20,
  },
});

export default Example;

License

MIT

Made with create-react-native-library