BeuiInfiniteMasonry<T> class

A columned, infinite-scroll masonry feed — the Flutter port of beUI's infinite-masonry block.

Items flow into a responsive number of columns (shortest-column-first), the feed auto-loads more as you approach the end, and it renders empty / loading / end / error tail states. New items (those appended after the initial batch) reveal with a per-lane-staggered spring rise + fade.

Windowing

The source uses measured lane positions and mounts only virtual items. This implementation retains each mounted item's measured height by stable key.

It computes shortest-lane positions from measured heights and mounts only viewport items plus overscan * columns around them.

  • Responsive columns — columns = min(maxColumns, max(1, floor((width + gap) / (minColumnWidth + gap)))), from a LayoutBuilder (the Flutter analog of the source's ResizeObserver), identical formula.
  • Shortest-column-first distribution — items use measured height when available, then estimateSize, to choose the next lane.
  • Windowed rendering — only virtual items are mounted, and measurements persist by stable key across scroll windows and column reflow.
  • Separate windows — overscan controls rendered items; prefetch controls the last-visible-index load trigger.

Trade-off: geometry is recomputed in O(n) per update, while mounted item widgets remain bounded to the viewport and overscan window.

Motion

Items with index >= items.length at mount reveal (unless animateItems is false or reduced motion is on): y: 12 → 0 on beuiSpringPanel plus opacity: 0 → 1 over 200ms beuiEaseOut, both delayed by min(lane, 3) * 0.04s. Each key reveals once — re-layout (e.g. a column count change) never re-triggers it. Reduced motion drops the reveal entirely (the source's useReducedMotion() branch).

Layout

This is a scrollable feed and expects a bounded height from its parent (wrap it in a SizedBox/Expanded), like any vertical scroll view.

Inheritance

Constructors

BeuiInfiniteMasonry({required List<T> items, required BeuiMasonryKeyBuilder<T> getItemKey, required BeuiMasonryItemBuilder<T> renderItem, required FutureOr<void> onLoadMore(), required bool hasMore, bool loading = false, Widget? error, VoidCallback? onRetry, BeuiMasonrySizeEstimator<T>? estimateSize, Widget renderLoadingItem(int index)?, Widget? emptyState, Widget? endState, double minColumnWidth = 208, int maxColumns = 4, double gap = 12, int overscan = 4, int prefetch = 3, bool animateItems = true, String ariaLabel = 'Infinite masonry feed', ScrollController? controller, Key? key})
Creates an infinite masonry feed.
const

Properties

animateItems → bool
Whether newly appended items reveal with the stagger spring. Ignored under reduced motion (source animateItems = true).
final
ariaLabel → String
Accessibility label for the feed region (source ariaLabel).
final
controller → ScrollController?
Optional external scroll controller. When null, an internal one is created and disposed.
final
emptyState → Widget?
Shown when the feed is empty and no more will load. Defaults to an Inbox glyph + copy (source emptyState).
final
endState → Widget?
Footer shown below the grid once everything has loaded (!hasMore) and the feed is non-empty (source endState).
final
error → Widget?
When non-null, renders an error tail card (with onRetry) instead of the loading skeletons (source error).
final
estimateSize → BeuiMasonrySizeEstimator<T>?
Estimated item height for lane assignment until measured at the current column width. Defaults to 240 (source estimateSize = () => 240).
final
gap → double
Gap between columns and between items, in px (source gap = 12).
final
getItemKey → BeuiMasonryKeyBuilder<T>
Returns the stable key for an item (source getItemKey).
final
hashCode → int
The hash code for this object.
no setterinherited
hasMore → bool
Whether more items remain to load (source hasMore).
final
items → List<T>
The currently loaded items, in feed order.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loading → bool
Whether a load is in flight — drives the pulsing skeleton tail (source loading).
final
maxColumns → int
Hard cap on the responsive column count (source maxColumns = 4).
final
minColumnWidth → double
Minimum column width; smaller viewports collapse to fewer columns (source minColumnWidth = 208).
final
onLoadMore → FutureOr<void> Function()
Called to fetch the next page when the feed nears its end. May be async; the feed guards against overlapping calls (source onLoadMore).
final
onRetry → VoidCallback?
Retry callback shown on the error tail card (source onRetry).
final
overscan → int
Extra rendered items per column before and after the visible range (source overscan = 4). It does not widen the load-more threshold.
final
prefetch → int
Loads more when the last visible item is within this many items of the end (source prefetch = 3).
final
renderItem → BeuiMasonryItemBuilder<T>
Builds an item's card (source renderItem).
final
renderLoadingItem → Widget Function(int index)?
Builds a loading skeleton for the tail at index (0-based within the tail). Defaults to a pulsing placeholder card (source renderLoadingItem).
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<BeuiInfiniteMasonry<T>>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited