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'sResizeObserver), 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
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- BeuiInfiniteMasonry
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 (sourceendState).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(sourceestimateSize = () => 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 (sourcerenderLoadingItem).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