Responsive GridView

A flexible, powerful, and responsive GridView for Flutter that adapts seamlessly across Mobile, Tablet, Desktop, and Web. Supports dynamic breakpoints, auto-fitting item widths, fixed column counts, on-demand list builders, and custom aspect ratios with pixel-perfect spacing.

---

✨ Features

• 📱 Multi-Platform Responsive Layout: Dynamically adjust columns across Mobile, Tablet, Laptop, Desktop, and 4K displays.
• 🎯 Responsive Breakpoints: Configure named breakpoints (xs, sm, md, lg, xl), custom pixel width maps, or dynamic calculation builders via ResponsiveColumns.
• 📐 Auto-Fit Item Widths: Specify minItemWidth or maxItemWidth and let the grid calculate the optimal number of columns automatically.
• ⚡ Builder Constructor: Lazy and efficient list rendering with ResponsiveGridView.builder.
• 🎨 Pixel-Perfect Spacing & Sizing: Equal column widths across all rows (including trailing odd-count rows) with independent horizontalSpacing and verticalSpacing.
• 🔲 Child Aspect Ratio: Easily enforce item aspect ratios (e.g., 16/9, 1:1, 4/3) with childAspectRatio.
• 🪶 Zero Boilerplate: Works as a drop-in widget inside SingleChildScrollView, Column, or standalone.
• 🔒 100% Type-Safe & Null-Safe: Built for Dart 3 and modern Flutter standards.

---

📦 Installation

Add responsive_gridview to your pubspec.yaml:

dependencies:
  responsive_gridview: ^2.0.0

Then run:

flutter pub get

---

🚀 Usage

Import the package in your Dart file:

import 'package:responsive_gridview/responsive_gridview.dart';

1. Responsive Breakpoints

Adapt column counts based on screen width using ResponsiveColumns:

ResponsiveGridView(
  columns: const ResponsiveColumns(
    xs: 1, // < 600px (Mobile portrait)
    sm: 2, // >= 600px (Tablet portrait / large phones)
    md: 3, // >= 900px (Tablet landscape / laptops)
    lg: 4, // >= 1200px (Desktops)
    xl: 6, // >= 1536px (Ultra-wide / 4K)
  ),
  horizontalSpacing: 16,
  verticalSpacing: 16,
  padding: const EdgeInsets.all(16),
  children: [
    Card(child: Center(child: Text('Card 1'))),
    Card(child: Center(child: Text('Card 2'))),
    Card(child: Center(child: Text('Card 3'))),
  ],
)

You can also use custom pixel breakpoints:

ResponsiveGridView(
  columns: ResponsiveColumns.breakpoints({
    0: 1,
    480: 2,
    768: 3,
    1024: 4,
    1440: 6,
  }),
  children: items,
)

---

2. Auto-Fit Columns by Minimum Item Width

Let the grid automatically compute the maximum number of columns such that each item is at least 200px wide:

ResponsiveGridView(
  minItemWidth: 200,
  horizontalSpacing: 12,
  verticalSpacing: 12,
  childAspectRatio: 1.2,
  children: items,
)

---

3. On-Demand Builder (ResponsiveGridView.builder)

Ideal for large datasets or dynamic items:

ResponsiveGridView.builder(
  minItemWidth: 180,
  horizontalSpacing: 16,
  verticalSpacing: 16,
  itemCount: 100,
  itemBuilder: (context, index) {
    return Card(
      child: Center(child: Text('Item #$index')),
    );
  },
)

---

4. Basic Fixed Columns Grid

For a fixed number of columns with custom spacing and aspect ratio:

ResponsiveGridView(
  column: 3,
  horizontalSpacing: 16,
  verticalSpacing: 16,
  padding: const EdgeInsets.all(16),
  childAspectRatio: 16 / 9,
  children: [
    Container(color: Colors.blue),
    Container(color: Colors.red),
    Container(color: Colors.green),
  ],
)

---

⚙️ Parameters

Parameter	Type	Description	Default
children	List<Widget>?	The list of widgets to display (for default constructor)	Required (default constructor)
itemCount	int	Total number of items (for ResponsiveGridView.builder)	Required (.builder)
itemBuilder	NullableIndexedWidgetBuilder	Item builder callback (for ResponsiveGridView.builder)	Required (.builder)
column	int?	Static number of columns	1 (if no other column setting is provided)
columns	ResponsiveColumns?	Breakpoint-based column resolver	null
minItemWidth	double?	Auto-fit columns by minimum item width in pixels	null
maxItemWidth	double?	Auto-fit columns by maximum item width in pixels	null
horizontalSpacing	double	Spacing between columns in pixels	12
verticalSpacing	double	Spacing between rows in pixels	12
padding	EdgeInsetsGeometry	Outer padding around the grid	EdgeInsets.all(12)
childAspectRatio	double?	Optional aspect ratio (width / height) for each cell	null
crossAxisAlignment	CrossAxisAlignment	Alignment of items in each row along the cross-axis	CrossAxisAlignment.start
mainAxisAlignment	MainAxisAlignment	Alignment of items along the row main-axis	MainAxisAlignment.start
shrinkWrap	bool	Whether the grid wraps its content size	true
physics	ScrollPhysics?	Scroll physics when shrinkWrap: false	null
controller	ScrollController?	Scroll controller when shrinkWrap: false	null

---

🛠️ Example App

Check out the example directory for a complete interactive Material 3 demo showcasing:

• Live Playground with dynamic sliders for columns, spacing, padding, and aspect ratio.
• Real-time Breakpoints preview with active breakpoint indicators.
• Auto-Fit card reflow simulation.
• On-demand builder with styled tiles.

To run the example app:

cd example
flutter run

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.