smart_layout

Intelligent list-to-grid layouts for responsive collection UIs in Flutter.

smart_layout helps you build responsive feeds, catalogs and galleries with minimal boilerplate.
Instead of manually switching between ListView and GridView for each breakpoint, you give intent, and smart_layout chooses the right layout.

✨ Features

  • 📱 Phone / tablet / desktop aware using a simple DeviceType model\
  • 🧠 Smart list vs grid decision based on device type and item count\
  • 🧩 Simple, opinionated API:
    • SmartLayoutBuilder -- gives you rich SmartLayoutInfo
    • SmartCollectionLayout -- auto list/grid for collections
  • 📐 Uses shortest side for device classification so a phone doesn't become a "tablet" when rotated\
  • ✅ Includes tests and an example app

🚀 Getting started

Add the dependency:

dependencies:
  smart_layout: ^0.1.0

(Use the latest version from pub.dev once published.)

🧠 Core concepts

SmartLayoutInfo

SmartLayoutInfo is a small immutable model that describes the current layout:

  • deviceType -- phone, tablet, desktop
  • sizeClass -- compact, regular, expanded
  • orientation -- portrait, landscape
  • size -- Size(width, height)
  • itemCount -- optional number of items for the current collection

You usually get this via SmartLayoutBuilder.

🧱 SmartLayoutBuilder

Low-level entry point: get a SmartLayoutInfo inside your widget tree.

SmartLayoutBuilder(
  itemCount: items.length,
  builder: (context, layout) {
    if (layout.isPhone) {
      return PhoneLayout(items: items);
    }

    if (layout.isTablet) {
      return TabletLayout(items: items);
    }

    return DesktopLayout(items: items);
  },
);

📚 SmartCollectionLayout (list ↔ grid)

High-level widget for collection UIs (feeds, menus, product grids, etc.).

SmartCollectionLayout(
  itemCount: items.length,
  itemBuilder: (context, index) {
    final item = items[index];
    return ProductCard(item: item);
  },
);

Default behavior

  • Uses a list on phones\
  • Uses a list on larger devices for very small collections (<= 4 items)\
  • Uses a grid on tablets / desktops when there is enough space and items

Grid columns are computed from width:

columns = clamp(
  floor(width / minGridTileWidth),
  1,
  maxGridColumns,
)

📸 Example

Run the provided example app:

cd example
flutter run

🧪 Testing

Run all tests:

flutter test

🛣 Roadmap

  • Configurable layout strategies\
  • Additional collection modes: feed, catalog, gallery\
  • Custom decision hooks\
  • Page layout helpers (header/body/sidebar)

🏷️ License

License: MIT see LICENSE.

Libraries

smart_layout