react-native-reshuffled 🔀

High-performance, Nitro-powered grid layout for React Native. Unlike standard lists, react-native-reshuffled provides a dynamic coordinate-based grid where every item transition is fluidly animated across both X and Y axes.

Android Demo 🤖

demo_android.mov

Android Demo 🍎

demo_ios.mov

⚡ Powered by Nitro Modules

This library is built on top of react-native-nitro-modules, leveraging the next generation of React Native architecture:

• Ultra-fast Serialization: Communication between JS and Native is handled via JSI with zero overhead.
• Type Safety: Fully typed modules ensure stability and a superior Developer Experience.
• Next-Gen Performance: Optimized for the New Architecture (TurboModules) and high-frequency layout updates.

✨ Features

• True Grid Layout: Break free from the linear constraints of FlatList.
• Smart Reordering: Items don't just "jump" to new slots; they calculate the shortest path and animate smoothly.
• Fully Responsive: Automatically recalculates positions on screen orientation or container size changes.
• Native Speed: Coordinate calculations are handled via Nitro-optimized native communication.

📦 Installation

First, install the main package:

npm install react-native-reshuffled

Peer Dependencies

Since this library utilizes modern animation and gesture engines, ensure you have the following installed in your project:

npm install react-native-nitro-modules react-native-reanimated react-native-gesture-handler

Note for iOS: Don't forget to run cd ios && pod install to link the native Nitro modules.

🚀 Quick Start

import React, { useState } from 'react';  
import { View, StyleSheet, TouchableOpacity, Text } from 'react-native';  
import { ReshuffledGrid } from 'react-native-reshuffled';

const App = () => {  
  const [data, setData] = useState([  
    { id: '1', color: '#6200EE', title: 'A', width:1, height: 1, startColumn: 0, startRow: 0 },  
    { id: '2', color: '#03DAC6', title: 'B', width:1, height: 1, startColumn: 1, startRow: 0 },  
    { id: '3', color: '#B00020', title: 'C', width:1, height: 1, startColumn: 0, startRow: 1 },  
    { id: '4', color: '#FFDE03', title: 'D', width:2, height: 1, startColumn: 0, startRow: 2 },  
  ]);

  return (  
    <View style={styles.container}>  
      <Text style={styles.btnText}>RESHUFFLED: GRID<Text>  

      <ReshuffledGrid
        data={data}  
        columns={2}
        rows={3}
        gapVertical={12}
        gapHorizontal={12}  
        renderItem={({ item }) => (  
          <View style={[styles.card, { backgroundColor: item.color }]}>  
             <Text style={styles.cardText}>{item.title}</Text>  
          </View>  
        )}  
      />  
    </View>  
  );  
};

const styles = StyleSheet.create({  
  container: { flex: 1, padding: 16, backgroundColor: '#f5f5f5' },  
  button: {   
    padding: 16,   
    backgroundColor: '#000',   
    marginBottom: 20,   
    alignItems: 'center',  
    borderRadius: 8   
  },  
  btnText: { color: '#fff', fontWeight: 'bold' },  
  card: {   
    flex: 1,   
    borderRadius: 12,   
    height: 150,   
    justifyContent: 'center',   
    alignItems: 'center'   
  },  
  cardText: { color: '#fff', fontSize: 24, fontWeight: 'bold' }  
});

⚙️ API Reference

ReshuffledGrid Props

Prop	Type	Description	Default
data	T[] extends Cell[]	Array of items to be rendered.	Required
renderItem	(info: {item: ItemT, index: number}) => React.ReactElement | null	Function returning a component for each item.	Required
renderItem	(info: {item: ItemT, index: number}) => React.ReactElement | null	Function returning a shadow component for each item.	null
rows	number	Number of rows in the grid.	Required
columns	number	Number of columns in the grid.	Required
style	StyleProp	Grid's CSS style.	Required
gapVertical	number	Vertical spacing between items in pixels.	0
gapHorizontal	number	Horizontal spacing between items in pixels.	0

🛠 Why not FlatList?

Standard FlatList is essentially a one-dimensional list that only allows for arranging elements in a single direction (linear sequence). Even when using the numColumns parameter, it remains constrained to a strict flow where items simply "snap" into fixed positions.

react-native-reshuffled breaks these limitations by allowing you to define a true 2D grid where components can be placed anywhere. More importantly, it enables dynamic reordering with fluid, high-performance animations, moving elements seamlessly across the layout rather than jumping from one index to another.It utilizes Nitro Modules to bridge the gap between JavaScript state and native layout positions, allowing elements to slide across the screen to their new coordinates smoothly.

🚧 Planned additions

react-native-reshuffled strives to deliver the most useful grid to developers and that's why I'm planning on also adding:

1. onChange callback, to let developers define extra actions' worklet, fired always when item gets moved.

If you think of some great, useful additions, let me know and I'll do my best to incorporate it here! 😃

📄 License

MIT © 2026