DOCSEARCHbyAlgolia
Submit Docs

React Native Sortables

repository·main·Indexed 21 days ago

https://github.com/matipl01/react-native-sortables

A high-performance library for implementing smooth content reordering in React Native applications using Grid and Flex layouts. Built on react-native-reanimated and react-native-gesture-handler, it supports both the Old and New Architectures, Expo, and Web. Key features include auto-scrolling, customizable layout animations, haptic feedback integration, and various reordering strategies such as insertion and swapping.

Tokens
25.9K
Snippets
85
Records
132
Agent score
74%

What's inside react-native-sortables

  1. Overview of React Native Sortables

    main

    React Native Sortables is a library designed for smooth drag-and-drop reordering of items in React Native applications. It provides ready-to-use sortable components that use intuitive gesture-based reordering, optimized for both iOS and Android.

    Key Capabilities

    • Flexible Layouts: Supports both Grid and Flex layouts, handles items with varying dimensions, and allows for customizable spacing.
    • Interactive Features: Includes auto-scrolling (when dragging near screen bounds), layout animations for adding/removing items, and support for multiple reordering strategies like insertion and swapping.
    • Developer Experience: Offers a simple API with minimal configuration, full TypeScript support, and compatibility with Expo.
    • Architecture Support: Works with both the New and Old React Native architectures.

  2. Use the Sortable Flex component

    main

    The Sortable Flex component provides a flex container that allows items to be reordered via drag-and-drop interactions. It supports complex flexbox layouts, making it more versatile than the Sortable Grid component.

    Note: The layout calculation for Sortable Flex is significantly more complex than Sortable Grid. For most standard use cases, it is recommended to use the Sortable Grid component instead.

  3. Key Features of React Native Sortables

    main

    React Native Sortables provides several advanced features for content reordering:

    • Flexible Layouts: Supports both Grid and Flex layouts, including support for items with different dimensions.
    • Performance: Built on react-native-reanimated and react-native-gesture-handler. It supports both the Old and New Architecture.
    • Rich Interactions: Includes auto-scrolling beyond screen bounds, customizable layout animations for adding/removing items, and optional haptic feedback integration (compatible with react-native-pulsar, expo-haptics, or react-native-haptic-feedback).
    • Reordering Strategies: Supports different strategies such as insertion and swapping.

  8. React Native Sortables dependencies and haptics support

    main

    React Native Sortables is built upon several core libraries and supports various haptic feedback implementations:

    Core Dependencies

    • react-native-reanimated
    • react-native-gesture-handler
    • react-native-pulsar (optional, for haptics)

    Optional Haptics Support

    Depending on your environment (e.g., Expo vs Bare workflow), you can use:

    • expo-haptics (for Expo projects)
    • react-native-haptic-feedback (for bare React Native projects)

  9. How Sortable.PortalProvider works

    main

    The PortalProvider creates a separate portal outlet higher in the view hierarchy. When an item becomes active, it is "teleported" to this outlet. The provider manages the synchronization of the teleported item's position with the original item and handles the visibility of the original item during the drag process.

    Key Behaviors to Note:

    • Active Item Copy: The portal renders a separate instance (a copy) of the active item. While dragging, both the original component (rendered but invisible) and the portal instance exist simultaneously.
    • Component State: Because the teleported component is a separate instance, local state (e.g., useState) is not shared between the original item and the portal copy. To maintain state during a drag, you must use Context providers, an external state management library, or lift the state up to a parent component.
    • Layout Animations: Since the item is mounted and unmounted within the portal outlet, any entering/exiting animations triggered on render will execute within the portal.
    • Paper (Old Architecture) Warning: If using the React Native Old Architecture, you might see a shadow-related warning. You can resolve this by setting activeItemShadowOpacity={0} or by ignoring the warning.

  10. Compatibility and Architecture Notes

    main

    Architecture Support

    • New Architecture: Fully supported. If using the New Architecture on iOS, it is recommended to use react-native-gesture-handler v3 to avoid issues where dragged items get 'stuck' when screens are detached/re-attached (e.g., in bottom tabs).
    • Old Architecture: Supported. react-native-gesture-handler v2.x is appropriate for the Old Architecture.
    • Expo: The library is Expo compatible.
    • Web: Supported via the provided web examples.

  11. Configure Haptic Feedback for react-native-sortables

    main

    Haptic feedback is an optional feature. The library automatically detects and uses the first available haptics package from the following list (in order of priority):

    1. react-native-pulsar: Provides rich haptic presets (requires the New Architecture).
    2. expo-haptics: For Expo-based projects.
    3. react-native-haptic-feedback: For bare React Native workflows.

  12. Use Sortable.Layer to manage zIndex during drags

    main

    The Sortable.Layer component manages zIndex to ensure that items being dragged remain visually above other components on the screen.

    When to use it: You should only use this component if you notice that a dragged item appears underneath other components on the screen. In most cases, react-native-sortables handles this internally, so you only need to wrap your components in Sortable.Layer if you encounter z-index layering issues.

    How it works:

    • It detects when a child item in a nested sortable component starts being dragged.
    • It automatically adjusts zIndex values to maintain the visual hierarchy.
    • If multiple Sortable.Layer components are nested, the drag information bubbles up, and zIndex is updated in each layer.
    import Sortable from 'react-native-sortables';

// ... other components
<Sortable.Layer>
  {/* ... other components */}
  <Sortable.Grid // or Sortable.Flex
  // ... sortable grid props
  />
  {/* ... other components */}
</Sortable.Layer>;
// ... other components