lazy_wrap

lazy_wrap brings lazy rendering to wrap-like Flutter layouts. It is designed for large collections of chips, tags, cards, and tiles without eagerly building every child.

Choose between two modes:

  • LazyWrap.fixed when every item has the same known dimensions.
  • LazyWrap.dynamic for variable or unknown item sizes.

Features

The Dynamic column describes the default offstageV1 engine.

Feature Fixed Dynamic
Lazy rendering ✅ ✅
Vertical and horizontal scrolling ✅ ✅
Variable item sizes — ✅
Offstage measurement — ✅
Optional fade-in — ✅
Batched loading — ✅
External ScrollController — ✅

The default offstageV1 engine for LazyWrap.dynamic uses exact measured row geometry, applies backpressure while measurement is in progress, and skips transparent fade frames during large scroll jumps. Automated rapid-scroll tests exercise reversals with large item counts; actual frame performance still depends on the device and child widgets.

Installation

dependencies:
  lazy_wrap: ^1.1.2
import 'package:lazy_wrap/lazy_wrap.dart';

Fixed-size items

Use LazyWrap.fixed when every item has the same width and height. The supplied dimensions are used to place items, so no offstage measurement pass is needed.

LazyWrap.fixed(
  itemCount: 10000,
  estimatedItemWidth: 120,
  estimatedItemHeight: 96,
  spacing: 8,
  runSpacing: 8,
  padding: const EdgeInsets.all(16),
  itemBuilder: (context, index) {
    return ProductCard(index: index);
  },
)

Despite their legacy estimated... names, the dimensions supplied to fixed mode are the actual layout dimensions. They should match the intended size of every child.

Variable-size items

Use LazyWrap.dynamic when item dimensions vary or cannot be known in advance. Items are measured offstage before they enter the visible wrap.

LazyWrap.dynamic(
  itemCount: 10000,
  spacing: 8,
  runSpacing: 8,
  padding: const EdgeInsets.all(16),
  itemBuilder: (context, index) {
    return Chip(label: Text('Tag $index'));
  },
)

Loading and animation

final controller = ScrollController();

LazyWrap.dynamic(
  itemCount: items.length,
  controller: controller,
  batchSize: 100,
  measureBatchSize: 20,
  loadThreshold: 400,
  cacheExtent: 400,
  fadeInItems: true,
  fadeInDuration: const Duration(milliseconds: 200),
  loadingBuilder: (context) {
    return const Padding(
      padding: EdgeInsets.all(16),
      child: Center(child: CircularProgressIndicator()),
    );
  },
  itemBuilder: (context, index) => VariableCard(items[index]),
)

For heavy widgets, keep measureBatchSize conservative. Increasing cacheExtent can make scrolling smoother at the cost of additional work and memory.

Choosing a mode

Scenario Recommended mode
Uniform cards or tiles with known dimensions LazyWrap.fixed
Chips and tags with different widths LazyWrap.dynamic
Items with variable heights LazyWrap.dynamic

Start with fixed mode whenever the dimensions are truly uniform. Otherwise, use dynamic mode with its default engine.

When existing data changes and may produce different item sizes, update layoutRevision on the dynamic widget to clear its cached measurements.

Dynamic API

The defaults and behavior in this table describe the default LazyWrapEngine.offstageV1 engine.

Parameter Default Description
itemCount Required Total number of items
itemBuilder Required Builds an item by index
spacing 8 Space between items in a run
runSpacing 8 Space between wrap runs
padding EdgeInsets.zero Padding around the content
rowAlignment MainAxisAlignment.start Alignment of items within each run
scrollDirection Axis.vertical Scroll axis
cacheExtent 300 Extra layout/cache extent around the viewport, in pixels
batchSize 50 Items admitted per load batch
measureBatchSize 15 Maximum items measured per pass
loadThreshold 300 Remaining distance that triggers loading
fadeInItems true Enables one-time item fade-in
fadeInDuration 200ms Duration of the optional fade-in
fadeInCurve Curves.easeOut Curve used for the optional fade-in
controller null Optional external ScrollController
loadingBuilder Default indicator Builds the loading indicator
engine LazyWrapEngine.offstageV1 Selects the dynamic layout engine
itemWidthBuilder null Required with experimental sliverV2
itemHeightBuilder null Required with experimental sliverV2
layoutRevision null Change when item data or inherited inputs can alter measured sizes

itemCount, spacing, runSpacing, cacheExtent, and the batch-related values must be non-negative; batch sizes must be greater than zero.

When data at existing indices or an inherited input used by itemBuilder may alter item dimensions, supply a new layoutRevision. Examples include reordering items or changing text scale. This clears the dynamic engine's cached layout state. If the widget uses its internal scroll controller, its scroll position resets.

Experimental engine

The default LazyWrapEngine.offstageV1 is the production path. An experimental vertical-only engine is also available for controlled evaluation:

LazyWrap.dynamic(
  itemCount: 50000,
  engine: LazyWrapEngine.sliverV2,
  itemWidthBuilder: (index) => 120 + (index % 4) * 12,
  itemHeightBuilder: (index) => 48 + (index % 3) * 8,
  itemBuilder: (context, index) => Card(
    child: Text('Item $index'),
  ),
)

sliverV2 calls both size builders for every item during initialization, then creates item widgets lazily as they approach the viewport. The default offstageV1 engine measures items in batches instead.

sliverV2 requires itemWidthBuilder and itemHeightBuilder, supports vertical scrolling only, and does not use batchSize, loadThreshold, measureBatchSize, loadingBuilder, or the fade-in settings.

Validation

The package test suite includes automated rapid-scroll regressions. An optional stress test in benchmarks/ loads 200,000 variable-size elements, reaches the last item, returns to the first, and repeatedly jumps between both edges. Device performance still depends on the complexity of each child.

The included example is a responsive playground with fixed and dynamic modes, 1K, 100K, and 1M item presets, adjustable item geometry and spacing, layout direction controls, and a generated code snippet. It also supports English and Spanish, plus light and dark themes. Dynamic items use deterministic variable sizes so their measurements can be explored interactively.

Run it from the repository root:

cd example
flutter pub get
flutter run -d chrome

Benchmarks

Performance comparisons cover LazyWrap.fixed only. LazyWrap.dynamic handles variable-size flow layouts and has no direct equivalent among the standard widgets below.

The current fixed-layout run used Flutter 3.47.9 and Chrome 156 on a Mac with an Apple M4 chip, at a 1280 × 832 CSS-pixel viewport and 60 Hz. Each implementation rendered the same 10,000 equal-size cards and used the same spacing, padding, cache extent, and 90-step scroll profile. The order rotated across six rounds per implementation.

Implementation p95 build (ms) p95 raster (ms) Jank (%) Time to interaction (ms)
LazyWrap.fixed 5.55 4.20–8.30 2.45 1.70–3.40 0.34 0.00–2.99 275.40 224.00–401.30
GridView.builder 7.35 5.50–11.50 2.95 2.20–4.40 3.34 0.67–28.24 304.15 247.10–367.80
ListView.builder with grouped rows 7.20 4.30–9.50 2.95 2.00–3.50 1.83 0.00–5.35 295.70 251.00–381.80

Values are the median across six runs; brackets show the minimum and maximum. Jank counts frames over the 16.67 ms budget. LazyWrap.fixed had the lowest median for these metrics in this run. The results describe one Mac/Chrome workload and show run-to-run variation; they are not a universal performance claim. An Android comparison for the current fixed implementation is still pending; earlier Android measurements used a prior iteration and are excluded.

See the benchmark notes and reproduction steps for the test harness and additional measurements.

Demo

LazyWrap Demo

Open the live demo

Support

If this package helps you, consider supporting its development:

ko-fi

Created by Hensell.

Libraries

lazy_wrap
Lazy Wrap