A virtual scroll component for large lists. Only the items visible in the viewport are rendered.

Element
igc-virtual-scroll
CSS Parts
virtualization-track — The full-size element that gives the host its scrollable extent.
virtualization-content — The wrapper that holds the rendered items, translated into position within the track.

The array of items to virtualize.

Compared by reference: a mutation in place (data.push(...)) causes no update. Assign a new array instead. The igcDataRequest flow also expects a new array.

data: T[] = []

Defined in src/components/virtualization/virtualization.ts:217

Estimated item size in pixels, used before an item is measured in the DOM. After the first render of an item, the engine replaces the estimate with the measured size.

estimatedItemSize: number = DEFAULT_ESTIMATED_ITEM_SIZE

Defined in src/components/virtualization/virtualization.ts:243

A function that renders each item in the virtual scroll list. Receives a VirtualScrollItemContext with the item data, its index, and the total count. Without it, nothing is rendered.

Items are measured by their border box, so margins accumulate as drift down the list. Use padding on the item, or a gap on a wrapper, instead.

Only the current window is in the DOM, so assistive technology cannot infer an item's position from the markup. Templates that render a role with set semantics (option, listitem, row, ...) should map the context's index and count onto aria-posinset and aria-setsize.

itemTemplate: VirtualScrollItemTemplate<T> | null = null

Defined in src/components/virtualization/virtualization.ts:259

Scroll orientation of the virtual scroll.

orientation: "horizontal" | "vertical" = 'vertical'

Defined in src/components/virtualization/virtualization.ts:225

Number of extra items to render beyond the visible area of the viewport. Higher values reduce blank flashes during fast scrolling but can lower performance.

overScan: number = 2

Defined in src/components/virtualization/virtualization.ts:234

The tagName read-only property of the Element interface returns the tag name of the element on which it's called.

MDN Reference

tagName: "igc-virtual-scroll" = 'igc-virtual-scroll'

Defined in src/components/virtualization/virtualization.ts:85

Resolves when the virtual scroll has settled: the current render pass is complete, the item-size measurements it triggers are complete, and so are the renders those measurements schedule.

updateComplete covers one Lit render pass. This covers data changes, scrolls, and viewport resizes, where the stable DOM state comes after one or more follow-up renders.

get layoutComplete(): Promise<void>

Defined in src/components/virtualization/virtualization.ts:813

Returns Promise<void>

connectedCallback(): void

Defined in src/components/virtualization/virtualization.ts:301

Returns void

createRenderRoot(): HTMLElement | DocumentFragment

Defined in src/components/virtualization/virtualization.ts:296

Returns HTMLElement | DocumentFragment

Scrolls to the specified item index.

Items outside the rendered window have only an estimated size, so the first jump can miss the target. The items at the landing point are then measured, and the scroll position is corrected. This repeats until the offset is stable.

The returned promise resolves when the scroll settles on the final, corrected offset. Callers that need only the first, approximate scroll can ignore it.

scrollToIndex(index: number, options: ScrollIntoViewOptions): Promise<void>

Defined in src/components/virtualization/virtualization.ts:832

Parameters

  • index: number
  • options: ScrollIntoViewOptions

Returns Promise<void>