# IgxVirtualScrollComponent

A high-performance virtual-scrolling component that renders only the items visible inside the viewport (plus a configurable over-scan buffer). It supports both vertical and horizontal axes, variable item sizes measured at runtime, lists far larger than the browser's maximum scroll coordinate, and remote / infinite scrolling through the `dataRequest` event.

## Imports

```ts
import {
    IgxVirtualScrollComponent,
    IgxVirtualItemDirective,
} from 'igniteui-angular/virtual-scroll';
```

---

## Basic usage

Define your list and provide a template using the `igxVirtualItem` directive:

```html
<igx-virtual-scroll [data]="items" style="height: 400px;">
    <ng-template igxVirtualItem let-item let-i="index">
        <div class="list-row">{{ i }}: {{ item.name }}</div>
    </ng-template>
</igx-virtual-scroll>
```

```ts
@Component({ /* ... */ })
export class MyComponent {
    items = Array.from({ length: 10_000 }, (_, i) => ({ name: `Item ${i}` }));
}
```

---

## Inputs

| Input | Type | Default | Description |
|---|---|---|---|
| `data` | `T[]` | `[]` | The array of items to virtualize. Compared by reference. See [Updating `data`](#updating-data). |
| `dataWindow` | `VirtualDataWindow<T> \| null` | `null` | A loaded page of a larger collection. Takes the place of `data` while it is set. See [Paged data](#paged-data). |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Scroll axis. |
| `overScan` | `number` | `2` | Extra items to render beyond each edge of the viewport. Higher values reduce blank flashes during fast scrolling at the cost of slightly more DOM nodes. Normalized to a non-negative integer. |
| `estimatedItemSize` | `number` | `50` | Pixel size used for items before they are measured in the DOM. Set this close to the real average size for the best initial-render accuracy. A non-positive value falls back to `50`. |
| `itemTemplate` | `TemplateRef<IgxVsItemContext<T>> \| null` | `null` | Programmatic template that takes precedence over a content `ng-template[igxVirtualItem]`. |
| `keyFunction` | `VirtualScrollKeyFunction<T> \| null` | `null` | Returns an item's key from the item and its index. Defaults to the index. See [Item elements and keys](#item-elements-and-keys). |


### Paged data

For data that arrives a page at a time, bind `dataWindow` instead of `data`:

```ts
interface VirtualDataWindow<T> {
    readonly items: readonly T[]; // The loaded page
    readonly startIndex: number;  // The index items[0] has in the whole collection
    readonly totalCount: number;  // How many items the whole collection has
}
```

The list is as long as `totalCount`, so the scrollbar spans the whole collection while only
the page is in memory. An index in the list is an index in that collection: the item at
`index` is `items[index - startIndex]`, and `IgxVsItemContext.index` and `.count` are the
global index and the total. Indices the page does not cover render nothing, so no template
is instantiated for an item that has not arrived.

`stateChange` reports the range the viewport wants, which is what a consumer supplies the
next page from:

```ts
load(state: VirtualScrollState) {
    const startIndex = state.startIndex;
    this.service.fetch(startIndex, state.endIndex - startIndex + 1)
        .subscribe(page => this.window = { items: page.rows, startIndex, totalCount: page.total });
}
```

Sizes are measured and kept per index, and the rows a new page renders are measured again in
the DOM, so moving the window costs the page rather than the collection. This assumes the
indexing stays stable while `totalCount` holds. A page with another `totalCount` is taken as a
different collection, a filtered one for instance, and every size is measured again. A sort that
keeps the count but puts different records at the same indices leaves the sizes measured for the
previous ones in place, for the indices that are not re-rendered.

`dataRequest` is not emitted in this mode — it asks for items to append, which a sized
collection does not need.

Paging keeps the *items* down to a page, not the size bookkeeping. The engine holds one size
entry per index, so its memory grows with `totalCount` rather than with the page: roughly
17 MB per million items. Give `totalCount` the size of the collection the consumer really
pages through; a value far beyond what the platform can allocate fails at the allocation.

### Lists inside a popup

A list inside a drop-down, dialog or any other container that is hidden until it opens has
no size to measure in the change detection pass that reveals it. The component learns its
size from a `ResizeObserver` and from `afterNextRender`, both of which run after a render,
so that first render is laid out against a viewport of zero and produces no rows. The rows
arrive in the next frame, once the host has been measured.

A wrapper that reacts to whether the list has children can flip state between those passes,
which Angular reports as `NG0100` in development mode. Read the rows after `layoutComplete`
instead.

A host with no box at all — hidden or detached — is not measured, because the zero it reports
says nothing about how large it will be once shown. Its last measurement is kept so the list
renders its window in the pass that reveals it again. The deliberate consequence is that the
rendered window stays in the DOM while the host is away.

Changing `estimatedItemSize` re-applies it to every item that has **not** yet been measured in the DOM. Items that have been measured keep their real size.

Unmeasured items then take the average measured size, so the scrollbar tracks real content. Later averages apply only while every item before the rendered window is measured and the list fits the browser's scroll limit, so rendered items never shift. A new `estimatedItemSize` restarts the average.

---

## Outputs

| Output | Payload | Description |
|---|---|---|
| `stateChange` | `VirtualScrollState` | Emitted when the virtual window changes. It reports the range the viewport wants, over-scan included; with `dataWindow` bound that range can reach past the loaded page, so it is not always the set of rows in the DOM. Consecutive renders that produce an identical window are not re-emitted. Once the host has been laid out, it is not emitted while the host is detached from the document, for example inside a closed drop-down; on re-attach the current window is emitted if it differs from the last one reported. |
| `dataRequest` | `VirtualScrollDataRequest` | Emitted when the rendered window comes within a few items of the end of `data`. Use this to implement infinite / remote scrolling. |

---

## Public API

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

Scrolls the viewport to the item at `index`.

Items outside the rendered window only have an *estimated* size, so the first jump can miss the target. The component measures the items at the landing point and corrects the scroll position, repeating until the offset is stable. The returned promise resolves on that final offset; callers that only need the first, approximate scroll can ignore it.

```ts
@ViewChild(IgxVirtualScrollComponent) vs!: IgxVirtualScrollComponent<any>;

// Leading edge, instant (the default).
await this.vs.scrollToIndex(500);

// Centered, animated.
await this.vs.scrollToIndex(500, { block: 'center', behavior: 'smooth' });

// Only scroll if the item is not already fully visible.
await this.vs.scrollToIndex(500, { block: 'nearest' });
```

| Option | Values | Notes |
|---|---|---|
| `block` | `'start'` \| `'center'` \| `'end'` \| `'nearest'` | Alignment on the vertical axis. Defaults to `'start'`. |
| `inline` | same as `block` | Alignment on the horizontal axis; falls back to `block`. |
| `behavior` | `'auto'` \| `'smooth'` | Defaults to `'auto'`. |

`'nearest'` leaves the scroll position untouched when the item is already fully in view, or when the item is larger than the viewport and currently covers it. Otherwise it scrolls the smallest distance that brings the item into view, as native `scrollIntoView({ block: 'nearest' })` does.

Out-of-range indices are clamped to the data, and the resulting offset is clamped to the largest reachable scroll position.

### `layoutComplete: Promise<void>`

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

Useful when you need to read the resulting DOM after a `data` change, a scroll, or a viewport resize:

```ts
this.items = await this.service.fetch();
await this.vs.layoutComplete;
// The rendered window and the track size now reflect the new data.
```

---

## `IgxVirtualItemDirective`

Marks an `ng-template` as the item template for the nearest `igx-virtual-scroll`. The template context is typed as `IgxVsItemContext<T>`.

### Template context variables

| Variable | Type | Description |
|---|---|---|
| `$implicit` (or `let-item`) | `T` | The current item. |
| `index` | `number` | The item's index within the full data array. |
| `count` | `number` | Total number of items in `data`. |
| `first` | `boolean` | `true` when `index === 0`. |
| `last` | `boolean` | `true` when `index === count - 1`. |
| `even` | `boolean` | `true` when `index` is even. |
| `odd` | `boolean` | `true` when `index` is odd. |

```html
<ng-template igxVirtualItem let-item let-i="index" let-first="first">
    <div [class.first-row]="first">{{ i }}: {{ item }}</div>
</ng-template>
```

---

## Output type reference

### `VirtualScrollState`

```ts
interface VirtualScrollState {
    startIndex: number;   // First item index of the wanted range
    endIndex: number;     // Last item index of the wanted range (inclusive)
    viewportSize: number; // Viewport height (or width) in px
    totalSize: number;    // Total virtual content size in px
}
```

The range is what the viewport wants, the over-scan buffer included. Bound to `data` that is
the set of rows in the DOM. Bound to `dataWindow` it is the range to load next, and the rows
actually rendered are its intersection with the page - which can be narrower, or empty.

### `VirtualScrollDataRequest`

```ts
interface VirtualScrollDataRequest {
    startIndex: number; // First index that does not yet have data
    count: number;      // Suggested number of items to fetch
}
```

---

## Updating `data`

`data` is compared **by reference**. Mutating the array in place (`items.push(...)`) does not trigger an update. Assign a new array instead.

The component diffs the new array against the previous one to decide which item measurements it can keep:

* **Appending** (`[...items, ...more]`) keeps the identity of every existing index, so all previous measurements are retained.
* **Replacing, filtering or sorting** invalidates every index from the first difference onwards; those items are measured again on their next render.

---

## Item elements and keys

Item elements are recycled: an item that stays in the window keeps its element, and leaving items hand theirs to entering ones, so a scroll step updates only the entering items. A focused element is not moved while its item stays in the window, so it keeps focus.

Without `keyFunction`, elements are keyed by index. Set it when items move within `data` (sort, insert, remove), so an element follows its item:

```html
<igx-virtual-scroll [data]="people" [keyFunction]="byId" style="height: 400px;">
    <ng-template igxVirtualItem let-person>
        <person-card [person]="person" />
    </ng-template>
</igx-virtual-scroll>
```

```ts
byId = (person: Person) => person.id;
```

Unbound DOM state, such as a checkbox toggled without `[checked]`, stays with a recycled element and shows on another item. Angular writes a binding only when its value changes, so bind all item state and write user changes back to the item:

```html
<ng-template igxVirtualItem let-task>
    <input type="checkbox" [checked]="task.done" (change)="task.done = $any($event.target).checked" />
</ng-template>
```

---

## Horizontal scrolling

Set `orientation="horizontal"`. Items are laid out in a row; ensure each item has an explicit `width` so the engine can measure sizes correctly.

```html
<igx-virtual-scroll [data]="items" orientation="horizontal" style="width: 100%; height: 60px;">
    <ng-template igxVirtualItem let-item>
        <div class="col" style="width: 120px; height: 60px;">{{ item }}</div>
    </ng-template>
</igx-virtual-scroll>
```

Right-to-left (RTL) layouts are fully supported. When the component (or an ancestor) sets `dir="rtl"`, horizontal scrolling, content positioning, and `scrollToIndex` are mirrored automatically. No extra configuration is required.

---

## Infinite / remote scrolling

Listen to the `dataRequest` output and append more items to the `data` array:

```html
<igx-virtual-scroll [data]="items" (dataRequest)="loadMore($event)" style="height: 500px;">
    <ng-template igxVirtualItem let-item>
        <div class="row">{{ item.label }}</div>
    </ng-template>
</igx-virtual-scroll>
```

```ts
loadMore(req: VirtualScrollDataRequest) {
    this.myService.fetch(req.startIndex, req.count).subscribe(newItems => {
        this.items = [...this.items, ...newItems];
    });
}
```

`dataRequest` is also emitted on the **first render** when the initially loaded items do not fill the viewport, so a short initial `data` array is enough to start the loading chain. An **empty** array is not: with nothing loaded there is no rendered window to run out of, so load the first page yourself and let `dataRequest` carry the rest.

Only one request is in flight at a time: the next one is emitted after `data` changes. If your source is exhausted and you reassign `data` without adding items, the component will not ask again for the same `startIndex`.

---

## Programmatic template

Pass a `TemplateRef` via `[itemTemplate]` when the template is defined outside the component:

```html
<ng-template #myTpl let-item>
    <div>{{ item }}</div>
</ng-template>

<igx-virtual-scroll [data]="items" [itemTemplate]="myTpl" style="height: 400px;" />
```

---

## Styling and DOM structure

```html
<igx-virtual-scroll class="igx-virtual-scroll" data-orientation="vertical" role="list">
    <div class="igx-virtual-scroll__track" role="presentation">      <!-- full virtual extent -->
        <div class="igx-virtual-scroll__content" role="presentation"><!-- translated into position -->
            <div class="igx-virtual-item" role="presentation" data-index="12">
                <!-- your item template -->
            </div>
            ...
        </div>
    </div>
</igx-virtual-scroll>
```

| Class / attribute | Element | Notes |
|---|---|---|
| `igx-virtual-scroll` | Host | Always present. |
| `data-orientation` | Host | Reflects the `orientation` input: `"vertical"` or `"horizontal"`. |
| `igx-virtual-scroll__track` | Inner spacer div | Sized to the full virtual height/width. |
| `igx-virtual-scroll__content` | Rendered-items wrapper | Absolutely positioned; translated to the correct virtual offset. |
| `igx-virtual-item` | Per-item wrapper | One per rendered item; carries `data-index` and is the element the engine measures. |

The host element must have a **fixed height** (vertical) or **fixed width** (horizontal) and `overflow: auto` or `overflow: scroll`. The default styles already set this.

### Item sizing

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

### Accessibility

Only the current window is in the DOM, so assistive technology cannot infer an item's position from the markup. The host carries `role="list"`; if your template renders a role with set semantics (`listitem`, `option`, `row`, ...), map the context's `index` and `count` onto `aria-posinset` and `aria-setsize`:

```html
<ng-template igxVirtualItem let-item let-i="index" let-count="count">
    <div role="listitem" [attr.aria-posinset]="i + 1" [attr.aria-setsize]="count">
        {{ item }}
    </div>
</ng-template>
```

---

## Very large lists

Browsers cap how far an element can scroll. When the total item size exceeds that limit, the component compresses the virtual coordinate space into the range the browser can represent and scales scroll positions accordingly. Items still render at their real pixel size, so lists of millions of items scroll correctly with no configuration.
