BloomVirtualizer class

Reactive list virtualization engine wrapping vendored @tanstack/virtual-core.

Restricts DOM rendering to only the items currently inside the visible viewport (plus an overscan margin), maintaining constant DOM memory and layout performance regardless of list size.

Required Lifecycle & Call Order

Construct: Instantiate BloomVirtualizer with a scrollElementRef, count, and estimateSize.
Attach on Mount: In a Mount or RefNode onMount callback, call attach. The container DOM element must already be mounted in the document.
Refresh on Change: Call refresh whenever the collection changes or count updates. Note: Calling refresh before the element is attached will throw.
Dispose on Unmount: Call dispose in onUnmount to release scroll and resize observers.

Example

final scrollRef = Ref<web.Element>();
final virtualizer = BloomVirtualizer(
  scrollElementRef: scrollRef,
  count: () => products.length,
  estimateSize: (index) => 64.0,
  overscan: 5,
);

RefNode(
  scrollRef,
  Mount(
    Div(
      style: 'height: 400px; overflow-y: auto; position: relative;',
      children: [
        Live(() => Div(
          style: 'height: ${virtualizer.totalSize.value}px; position: relative; width: 100%;',
          children: virtualizer.items.value.map((item) {
            final product = products[item.index];
            return Div(
              style: 'position: absolute; top: 0; left: 0; width: 100%; '
                     'height: ${item.size}px; transform: translateY(${item.start}px);',
              text: product.name,
            );
          }).toList(),
        )),
      ],
    ),
    onMount: virtualizer.attach,
    onUnmount: virtualizer.dispose,
  ),
);

Constructors

BloomVirtualizer({required Ref<Element> scrollElementRef, required int count(), required double estimateSize(int index), int overscan = 5, double gap = 0}): Creates a BloomVirtualizer configured with the specified scrolling container and sizing options.

Properties

count → int Function(): Callback returning the total number of items in the full dataset.
final
estimateSize → double Function(int index): Callback estimating the height in pixels of an item at index.
final
gap → double: Fixed gap in pixels between consecutive items. Defaults to 0.
final
hashCode → int: The hash code for this object.
no setterinherited
items → Signal<List<BloomVirtualItem>>: Reactive signal containing the list of BloomVirtualItems currently in the visible window.
final
overscan → int: Number of extra items rendered above and below the visible viewport. Defaults to 5.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scrollElementRef → Ref<Element>: Reference to the scrollable container DOM element (overflow-y: auto).
final
totalSize → Signal<double>: Reactive signal containing the total estimated scrollable height in pixels.
final

Methods

attach() → void: Connects scroll and resize observers to scrollElementRef and performs the initial measurement pass.
dispose() → void: Disconnects scroll and resize observers and releases internal JS resources.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
refresh() → void: Recomputes virtual window layout after count or dataset dimensions change.
toString() → String: A string representation of this object.
inherited

Operators

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