React Native Flexible Grid

React Native Flexible Grid is an advanced grid layout system inspired by CSS Grid, designed to facilitate responsive, customizable, and dynamic grid layouts in React Native applications. It supports both responsive and fixed layouts, enabling the creation of intricate designs with minimal effort.

🌟 Features

• Responsive Design: Adapts fluidly to both screen and container sizes, ensuring your content looks perfect on any device. This guarantees that your grid will seamlessly accommodate different resolutions and orientations, making it ideal for responsive mobile applications.
• Dynamic Item Sizing: Offers great flexibility to define both fixed and dynamic grid item dimensions, enabling a diverse range of layout configurations. Whether you're aiming for a Masonry-style list, arranging items with uneven widths and heights, or replicating complex layouts similar to Instagram Explore and Pinterest.
• Virtualization Support: Dramatically boosts the performance of grids handling large data by employing virtualization. By rendering only the items in the immediate viewport and a buffer zone, this feature ensures smooth scrolling and responsive interactions.
• Two-Way Scrolling Support: Facilitates navigation beyond the initial viewport in both horizontal and vertical directions. This advanced scrolling capability enhances user experience by providing fluid access to off-screen content, making it easier to explore large grids without compromising on performance.
• Customizable: Offers a wide range of customization options, allowing fine-tuning of the grid according to specific requirements. From styling adjustments to functional tweaks.
• Minimal Dependencies: Built exclusively with React Native components for better integration and ensures broad compatibility while maintaining a minimal footprint.
• Universal Compatibility: Seamlessly supports Android & iOS and tested extensively with Expo & web.

🎥 Demo

📦 Installation

npm install react-native-flexible-grid

or

yarn add react-native-flexible-grid

💡 Usage

1. Flex Grid

FlexGrid is designed for creating highly flexible and dynamic grid layouts, capable of two-way scrolling to accommodate content that extends beyond both the viewport's width and height. By leveraging maxColumnRatioUnits, itemSizeUnit, and smooth scrolling mechanics, FlexGrid facilitates precise control over the grid's arrangement, dimensions, and scrolling behavior. This makes it exceptionally suited for applications requiring a versatile grid system that can display content in both horizontally and vertically overflowed layouts with ease.

Use Cases:

• Interactive Galleries: Optimal for galleries where users can explore content through both horizontal and vertical navigation.
• Board Layout: Ideal for creating grid board with documents or media or files in a grid that exceeds the viewport, allowing for comprehensive exploration.
• Complex Layouts: Perfect for applications demanding intricate grid arrangements that go beyond simple lists, including dashboards or design portfolios.

import { FlexGrid } from 'react-native-flexible-grid';

export default function App() {
  const data = [
    { imageUrl: 'https://picsum.photos/200/300?random=1', widthRatio: 1, heightRatio: 1, text: "Item 1", id: 1 },
    { imageUrl: 'https://picsum.photos/200/300?random=2', widthRatio: 2, heightRatio: 1, text: "Item 2", id: 2 },
    { imageUrl: 'https://picsum.photos/200/300?random=3', widthRatio: 2, heightRatio: 1, text: "Item 3", id: 3 },
  ];

  const renderItem = ({item, index}) => (
      <View style={styles.boxContainer}>
        <Image
          source={{ uri: item.imageUrl }}
          style={styles.box}
          resizeMode="cover"
        />
        <Text style={styles.text}>{item.text}</Text>
      </View>
  );

  return (
    <View style={styles.container}>
      <FlexGrid
        keyExtractor={(item) => item.id.toString()}
        maxColumnRatioUnits={60}
        itemSizeUnit={60}
        data={data}
        virtualizedBufferFactor={2}
        renderItem={renderItem}
        virtualization={true}
        showScrollIndicator={false}
        style={{ flex: 1 }}
      />
    </View>
  );
}

See Examples:

1. Grid Board Example

2. Responsive Grid

The ResponsiveGrid is designed for optimal responsiveness, dynamically adjusting grid items based on the container's width or a specified width within the component's style properties. Utilizing a combination of maxItemsPerColumn alongside item-specific widthRatio and heightRatio, it efficiently organizes content into a vertically scrollable grid. This component is ideally suited for layouts where vertical scrolling is preferred and where the grid's adaptability to varying container widths or device width is crucial.

Use Cases:

• Content Feeds: Perfect for vertically scrolling content feeds that require adaptability to different screen sizes.
• Image Galleries: Ideal for image galleries where images need to be displayed in a responsive, organized or uneven manner.
• Product Listings: Suitable for e-commerce apps needing to showcase products in a neatly arranged, responsive grid.

import { ResponsiveGrid } from 'react-native-flexible-grid';

export default function App() {
  const data = [
    { imageUrl: 'https://picsum.photos/200/300?random=1', widthRatio: 1, heightRatio: 1, text: "Item 1", id: 1 },
    { imageUrl: 'https://picsum.photos/200/300?random=2', widthRatio: 2, heightRatio: 1, text: "Item 2", id: 2 },
    { imageUrl: 'https://picsum.photos/200/300?random=3', widthRatio: 2, heightRatio: 1, text: "Item 3", id: 3 },
  ];

  const renderItem = ({item, index}) => (
  <View style={styles.boxContainer}>
        <Image
          source={{ uri: item.imageUrl }}
          style={styles.box}
          resizeMode="cover"
        />
      </View>
  );

  return (
    <View style={styles.container}>
      <ResponsiveGrid
        keyExtractor={(item) => item.id.toString()}
        maxItemsPerColumn={3}
        data={data}
        renderItem={renderItem}
        style={{ padding: 5 }}
      />
    </View>
  );
}

See Examples:

1. Instagram Explore Example
2. Pinterest Example

⚙️ Props

1. FlexGrid Props

A higher buffer factor increases the number of items pre-loaded outside the viewport, contributing to a smoother scrolling experience as more content is ready for immediate display when scrolling. However, setting a large buffer factor can affect overall performance, especially on devices with limited resources, as it increases the number of components rendered off-screen.

While, a lower buffer factor reduces the off-screen component count, optimizing performance and resource usage. This setting is beneficial for large data or resource-constrained environments. However, it may lead to brief moments where content needs to catch up with the user's scroll speed, momentarily displaying blank areas until new items are rendered. scrollEventInterval Number 200 false Defines the interval, in milliseconds, at which scroll events are processed for the purpose of recalculating visible items and buffer in a virtualized grid. By setting this prop, developers can throttle the frequency of scroll event handling, optimizing performance during rapid scrolling by reducing the computational load associated with updating the list of visible items and buffer.

A lower value results in more frequent updates, offering smoother visual updates of the grid's content at the potential cost of higher computational overhead. While, a higher interval decreases the frequency of updates, potentially improving performance but with less immediate recalculation triggered by scroll actions. This is crucial for fine-tuning the performance and experience of virtualized grid.

2. ResponsiveGrid Props

A higher buffer factor increases the number of items pre-loaded outside the viewport, contributing to a smoother scrolling experience as more content is ready for immediate display when scrolling. However, setting a large buffer factor can affect overall performance, especially on devices with limited resources, as it increases the number of components rendered off-screen.

While, a lower buffer factor reduces the off-screen component count, optimizing performance and resource usage. This setting is beneficial for large data or resource-constrained environments. However, it may lead to brief moments where content needs to catch up with the user's scroll speed, momentarily displaying blank areas until new items are rendered. scrollEventInterval Number 200 false Defines the interval, in milliseconds, at which scroll events are processed for the purpose of recalculating visible items and buffer in a virtualized grid. By setting this prop, developers can throttle the frequency of scroll event handling, optimizing performance during rapid scrolling by reducing the computational load associated with updating the list of visible items and buffer.

A lower value results in more frequent updates, offering smoother visual updates of the grid's content at the potential cost of higher computational overhead. While, a higher interval decreases the frequency of updates, potentially improving performance but with less immediate recalculation triggered by scroll actions. This is crucial for fine-tuning the performance and experience of virtualized grid.

🚀 Vision and Roadmap

Our mission is not just to provide a flexible layout solution but to improve grid systems and layout flexibility in React Native. By continuously refining our algorithm and incorporating feedback, we aim to bring CSS Grid-like capabilities to the React Native ecosystem, fostering creativity and pushing the boundaries of what's possible in app design with React Native.

🤝 Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

📄 License

MIT