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.
Properties
Section titled "Properties"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
estimatedItemSize
Section titled "estimatedItemSize"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
itemTemplate
Section titled "itemTemplate"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
orientation
Section titled "orientation"Scroll orientation of the virtual scroll.
orientation: "horizontal" | "vertical" = 'vertical' Defined in src/components/virtualization/virtualization.ts:225
overScan
Section titled "overScan"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
tagName
Section titled "tagName"The tagName read-only property of the Element interface returns the tag name of the element on which it's called.
tagName: "igc-virtual-scroll" = 'igc-virtual-scroll' Defined in src/components/virtualization/virtualization.ts:85
Accessors
Section titled "Accessors"layoutComplete
Section titled "layoutComplete"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>
Methods
Section titled "Methods"connectedCallback
Section titled "connectedCallback"connectedCallback(): void Defined in src/components/virtualization/virtualization.ts:301
Returns void
createRenderRoot
Section titled "createRenderRoot"createRenderRoot(): HTMLElement | DocumentFragment Defined in src/components/virtualization/virtualization.ts:296
Returns HTMLElement | DocumentFragment
scrollToIndex
Section titled "scrollToIndex"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