Chapter 8: VirtualItem

Core Idea

A VirtualItem is the small geometry record passed to rendering code. It identifies the source index and key, then supplies start, end, size, and lane information for positioning.

Key Concepts

• key: The identity used by the rendered item; use a stable domain key when records can move.
• index: The source array index used to retrieve application data.
• start: The item's start offset along the active axis.
• end: The item's end offset along the active axis.
• size: The estimate before measurement, or the measured size afterward.
• lane: The lane assigned in a multi-lane layout.
• Estimated geometry: Before measurement, size comes from estimateSize.
• Measured geometry: Default element measurement uses the element's bounding rectangle.

Code Examples

{virtualizer.getVirtualItems().map((virtualItem) => (
  <div
    key={virtualItem.key}
    data-index={virtualItem.index}
    style={{
      position: 'absolute',
      transform: `translateY(${virtualItem.start}px)`,
      height: `${virtualItem.size}px`,
    }}
  >
    {items[virtualItem.index].label}
  </div>
))}

• What it demonstrates: Use the record's identity, source index, start offset, and size to render one item.

Key Takeaways

1. Use key for rendered identity and index for data lookup.
2. Map start and size to the active CSS axis.
3. Use lane when laying out masonry or multi-lane content.
4. Expect geometry to change after dynamic measurement.

Connects To

• Ch 007: The Virtualizer creates and updates these records.
• Ch 009: Fixed examples consume size directly.
• Ch 011: Measured examples show estimates becoming actual sizes.