lazy_wrap 1.1.3
lazy_wrap: ^1.1.3 copied to clipboard
A Flutter widget for lazy Wrap-style layouts with fixed or variable item sizes.
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.fixedwhen every item has the same known dimensions.LazyWrap.dynamicfor 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.3
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.

The bars show six-run medians; whiskers show the minimum and maximum. In this
run, median p95 build time was 5.55 ms for LazyWrap.fixed, 7.35 ms for
GridView.builder, and 7.20 ms for the row-grouped ListView.builder. Median
jank was 0.34%, 3.34%, and 1.83%, respectively. Jank counts frames over
the 16.67 ms budget.
These results describe one Mac/Chrome workload; they show run-to-run variation and 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 full metrics table, benchmark notes, and reproduction steps for p95 raster time, time to first interaction, ranges, and the test harness.
Demo #

Support #
If this package helps you, consider supporting its development:
Created by Hensell.