diff --git a/cspell.json b/cspell.json
index 42f68b5116..0310eeacdf 100644
--- a/cspell.json
+++ b/cspell.json
@@ -33,6 +33,8 @@
],
"words": [
"Figma",
+ "DoDont",
+ "dont",
"IgniteUI",
"Ignite",
"DocFX",
diff --git a/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png
new file mode 100644
index 0000000000..5aa26700cb
Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png differ
diff --git a/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png
new file mode 100644
index 0000000000..3772d6bce2
Binary files /dev/null and b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png differ
diff --git a/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png
new file mode 100644
index 0000000000..8d3349ca03
Binary files /dev/null and b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png differ
diff --git a/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png
new file mode 100644
index 0000000000..5aa26700cb
Binary files /dev/null and b/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png differ
diff --git a/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png
new file mode 100644
index 0000000000..3772d6bce2
Binary files /dev/null and b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png differ
diff --git a/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png
new file mode 100644
index 0000000000..8d3349ca03
Binary files /dev/null and b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png differ
diff --git a/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png
new file mode 100644
index 0000000000..5aa26700cb
Binary files /dev/null and b/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png differ
diff --git a/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png
new file mode 100644
index 0000000000..3772d6bce2
Binary files /dev/null and b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png differ
diff --git a/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png
new file mode 100644
index 0000000000..8d3349ca03
Binary files /dev/null and b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png differ
diff --git a/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx b/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx
index 8ffc42f3d3..e9870c4e87 100644
--- a/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx
+++ b/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx
@@ -2,19 +2,23 @@
title: "Virtual Scroll"
description: "The Virtual Scroll is a component that renders only the items in its viewport plus a small buffer, so large lists scroll smoothly."
keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}"
-last_updated: "2026-09-17"
+last_updated: "2026-09-25"
license: MIT
mentionedTypes: ["VirtualScroll"]
-relatedComponents: ["List", "Card"]
+relatedComponents: ["List", "Grid", "Card"]
llms:
description: "The {ProductName} Virtual Scroll is a component that renders large lists by keeping only the items in its viewport, plus a configurable buffer, in the DOM."
---
-import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro';
import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro';
import Sample from 'igniteui-astro-components/components/mdx/Sample.astro';
import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro';
+import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro';
import Faq from 'igniteui-astro-components/components/mdx/Faq.astro';
import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro';
+import { Image } from 'astro:assets';
+import virtualScrollAnatomy from '@xplat-images/anatomy-content-light/virtual-scroll-lt-a.png';
+import virtualScrollDo from '@xplat-images/virtual-scroll/virtual-scroll-do.png';
+import virtualScrollDoNot from '@xplat-images/virtual-scroll/virtual-scroll-do-not.png';
# Virtual Scroll Component
@@ -28,7 +32,7 @@ The {ProductName} Virtual Scroll is a component that renders large lists by keep
-
+
@@ -38,7 +42,27 @@ The {ProductName} Virtual Scroll is a component that renders large lists by keep
The {Platform} Virtual Scroll renders the visible items plus a configurable buffer, and its track preserves the scroll range of the whole collection.
-{/*TODO: add the Virtual Scroll anatomy image and render it with the component.*/}
+
+
+
+
+1. Host: The scroll container. Its fixed height (width when horizontal) sets how many items are visible.
+2. Track: A spacer sized to the estimated length of the whole collection, so the scrollbar spans every item.
+3. Content element: Holds only the rendered items. It starts at the first rendered buffer item, above the viewport, and takes its size from the rendered items.
+4. Item wrapper: One per rendered item. It hosts the item template and is the box that gets measured.
+5. Over-scan buffer: The overScan items (2 by default) rendered past each edge of the viewport.
@@ -51,7 +75,7 @@ igx-virtual-scroll — scrollable viewport (role="list")
-
+
```text
igc-virtual-scroll — scrollable viewport
@@ -115,7 +139,32 @@ virtualScroll.data = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${
-The Virtual Scroll host needs a fixed height for vertical scrolling or a fixed width for horizontal scrolling. A host that grows with its content has no viewport to fill.
+
+
+Set up {ProductName} with the [Getting Started](../general-getting-started.mdx) topic, then import the and give it an item template and data. The React wrapper registers the underlying element when the module loads, so no registration call is needed:
+
+```tsx
+import { IgrVirtualScroll } from 'igniteui-react';
+import type { VirtualScrollItemContext } from 'igniteui-react';
+
+const items = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${i}` }));
+
+export function Employees() {
+ return (
+ ) => (
+
{ctx.index}: {ctx.value.name}
+ )}
+ style={{ height: '400px' }}
+ />
+ );
+}
+```
+
+
+
+The Virtual Scroll host needs a fixed height for vertical scrolling or a fixed width for horizontal scrolling. A host that grows with its content renders every item, so the list is not virtualized.
### Prerequisites and Version Compatibility
@@ -139,6 +188,18 @@ The Virtual Scroll host needs a fixed height for vertical scrolling or a fixed w
+
+
+| Requirement | Value |
+| --- | --- |
+| Package | `igniteui-react` (MIT) |
+| First release with the component | 19.9.0 |
+| Peer packages | `react` and `react-dom` 18 or 19 |
+| Item templates | JSX returned from a function. `igniteui-webcomponents` comes in as a dependency of `igniteui-react`; you do not install it yourself. |
+| Theme | Import a theme stylesheet once, for example `igniteui-webcomponents/themes/light/bootstrap.css`. |
+
+
+
## Usage
### Item Template
@@ -151,7 +212,7 @@ Mark an `ng-template` with `igxVirtualItem`, or pass a template defined elsewher
```html
-
+
@@ -181,6 +242,27 @@ virtualScroll.itemTemplate = (ctx: VirtualScrollItemContext) => html`
+
+
+Set to a function that returns JSX. The function receives a `VirtualScrollItemContext` with `value` (the item), `index`, `count`, `isFirst`, and `isLast`. Without an item template, the component renders nothing.
+
+```tsx
+) => (
+
+
+ {ctx.value.name}
+ {ctx.value.email}
+
+ )}
+ style={{ height: '480px' }}
+/>
+```
+
+
+
### Data
The Virtual Scroll collection is compared by reference. Assign a new array to update the list; changing the bound array in place, for example with `push`, does not update it.
@@ -201,11 +283,41 @@ virtualScroll.data = [...virtualScroll.data, newEmployee];
+
+
+```tsx
+setEmployees(current => [...current, newEmployee]);
+```
+
+
+
When `data` changes, the component keeps the measured sizes of the items before the first changed index and measures the rest again when they render. Appending keeps every existing measurement; replacing, filtering, or sorting discards the measurements from the first changed item onwards.
+
+
+An item keeps its element while its key is in the rendered window. Without the index is the key, so after a sort, an insert, or a removal the element at an index stays put and shows its new item. Return a stable id from `keyFunction` when items move within `data`:
+
+```ts
+virtualScroll.keyFunction = (employee) => employee.id;
+```
+
+
+
### Estimated Item Size
-The Virtual Scroll is the size in pixels an item has until it renders and is measured (`50` by default). Items can have different sizes: each measured size replaces the estimate. Set the estimate close to the average item size to keep the scrollbar and `scrollToIndex` accurate before items are measured.
+The Virtual Scroll is the size in pixels an item has until it renders and is measured (`50` by default). Items can have different sizes: each measured size replaces the estimate.
+
+
+
+Set the estimate close to the average item size to keep the scrollbar and `scrollToIndex` accurate before items are measured.
+
+
+
+
+
+Set the estimate close to the average item size so that the first render lands near the real content. Once items are measured, their average replaces the estimate for the items that are not measured yet, so the scrollbar and `scrollToIndex` correct themselves even when the estimate is off.
+
+
@@ -227,6 +339,16 @@ The Virtual Scroll
+
+
+```tsx
+
+```
+
+
+
+
+
Items are measured by their border box, so margins are not part of an item's size. Space items with padding, or with a `gap` inside the item, instead of margins.
### Orientation
@@ -257,6 +379,22 @@ The Virtual Scroll
+
+```tsx
+
...
}
+ style={{ height: '200px' }}
+/>
+```
+
+
+
+
+
### Over-Scan
The Virtual Scroll is the number of extra items rendered beyond each edge of the viewport (`2` by default). A larger value reduces blank areas during fast scrolling and renders more elements.
@@ -277,6 +415,14 @@ The Virtual Scroll
+
+```tsx
+
+```
+
+
+
### Scroll to Index
The Virtual Scroll method scrolls an item into view. Its options are those of the native `scrollIntoView`: `block` (`start`, `center`, `end`, or `nearest`), `inline` for a horizontal list, and `behavior` (`auto` or `smooth`). Items that have not rendered only have an estimated size, so the component measures the items where it lands and corrects the position; the returned promise resolves on the final position.
@@ -305,6 +451,20 @@ await virtualScroll.scrollToIndex(index, { block: 'center' });
+
+
+```tsx
+const virtualScroll = useRef(null);
+
+async function goTo(index: number): Promise {
+ await virtualScroll.current?.scrollToIndex(index, { block: 'center' });
+}
+```
+
+
+
+
+
With `block: 'nearest'`, the position does not change when the item is already fully visible. Indices outside the collection are clamped to the first or last item.
### Infinite Scroll
@@ -350,6 +510,27 @@ virtualScroll.addEventListener('igcDataRequest', (event: CustomEvent
+
+
+The Virtual Scroll `onDataRequest` event supports append-only loading from remote data. It is emitted when the rendered window nears the end of `data`, and on the first render when the loaded items do not fill the viewport. Append the requested items as a new array:
+
+```tsx
+) => {
+ const { startIndex, count } = event.detail;
+ const page = await fetchEmployees(startIndex, count);
+ setEmployees(current => [...current, ...page]);
+ }}
+ style={{ height: '440px' }}
+/>
+```
+
+
+
+
+
Only one data request is pending at a time; the next one follows the next `data` change. An empty `data` emits no request, so load the first page yourself. When the source has no more items, stop appending: the component does not request the same start index again.
@@ -422,32 +603,130 @@ await virtualScroll.layoutComplete;
+
+
+```tsx
+setEmployees(await fetchEmployees());
+await virtualScroll.current?.layoutComplete;
+```
+
+
+
### Do/Don't
-{/*TODO: add the Virtual Scroll Do/Don't guidance image from Indigo.Design when it is available.*/}
+The Virtual Scroll usually works as the scroll container of a long list, keeping only the items in its viewport, plus a small buffer, in the DOM. Avoid it for a list short enough to render at once, and as you write the item template, keep each item state in the data rather than in its elements: item elements are reused, so DOM state the template does not bind shows on whichever item takes the element.
+
+
+
+
+
+
+
+
+
+Do
+
+Use the Virtual Scroll for a long list that is too large to render at once, such as a directory, a feed, a log, or a strip of cards, including lists that load remote data while scrolling.
+
+
+
+
+
+
+
+
+Don't
-**When to use:** Use the Virtual Scroll for a long list that is too large to render at once, such as a directory, a feed, a log, or a strip of cards, including lists that load remote data while scrolling.
-
-**When not to use:** Render a short list directly with the [List](../list.mdx) and `@for`. Use the [Grid](../grid/grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](../card.mdx) elements without virtualization.
+Render a short list directly with the [List](../list.mdx) and `@for`. Use the [{Platform} Data Grid](../grid/grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](../card.mdx) elements without virtualization.
-
-
-**When to use:** Use the Virtual Scroll for a long list that is too large to render at once, such as a directory, a feed, a log, or a strip of cards, including lists that load remote data while scrolling.
+
-**When not to use:** Render a short list directly with the [List](../grids/list.mdx). Show a small set of rich items as [Card](./card.mdx) elements without virtualization.
+Render a short list directly with the [List](../grids/list.mdx). Use the [{Platform} Data Grid](../grids/data-grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](./card.mdx) elements without virtualization.
-| Do | Don't |
-| --- | --- |
-| Give the host a fixed height (vertical) or width (horizontal). | Let the host grow with its content. |
-| Set `estimatedItemSize` close to the average item size. | Keep the 50px default for much larger or smaller items. |
-| Assign a new array when the collection changes. | Change the bound array in place. |
-| Space items with padding or `gap`. | Space items with margins. |
+
+
+
## Properties
@@ -474,10 +753,25 @@ await virtualScroll.layoutComplete;
| | `number` | `2` | Extra items rendered beyond each edge of the viewport. Attribute: `over-scan`. |
| | `number` | `50` | The size in pixels of an item until it is measured. A non-positive value uses `50`. Attribute: `estimated-item-size`. |
| | `VirtualScrollItemTemplate \| null` | `null` | The function that renders each item. Property only. |
+| | `VirtualScrollKeyFunction \| null` | `null` | Returns an item's key, so an item keeps its element when it moves in `data`. Without it, the index is the key. Property only. |
| | `Promise` (read-only) | — | Resolves when rendering and item measurement have settled. |
+
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| | `any[]` | `[]` | The collection to virtualize. Compared by reference. |
+| | `'vertical' \| 'horizontal'` | `'vertical'` | The scroll axis. |
+| | `number` | `2` | Extra items rendered beyond each edge of the viewport. |
+| | `number` | `50` | The size in pixels of an item until it is measured. A non-positive value uses `50`. |
+| | `(ctx: VirtualScrollItemContext) => ReactNode` | `null` | The function that renders each item. |
+| | `(item, index) => unknown` | `null` | Returns an item's key, so an item keeps its element when it moves in `data`. Without it, the index is the key. |
+| | `Promise` (read-only) | — | Resolves when rendering and item measurement have settled. Read it from a ref, not as a prop. |
+
+
+
## Methods
| Name | Returns | Description |
@@ -504,6 +798,17 @@ await virtualScroll.layoutComplete;
+
+
+| Name | Argument | Description |
+| --- | --- | --- |
+| `onStateChange` | `CustomEvent` | Emitted when the rendered window changes. `event.detail` carries `startIndex`, `endIndex`, `viewportSize`, `totalSize`. |
+| `onDataRequest` | `CustomEvent` | Emitted when the rendered window nears the end of `data`. `event.detail` carries `startIndex` and `count`. |
+
+The handlers receive the native `CustomEvent`, so read the payload from `event.detail`.
+
+
+
## Styling
The {Platform} Virtual Scroll has no theme of its own: it lays out the viewport, and the rendered items take their styles from the elements and components in the item template.
@@ -524,7 +829,7 @@ Size the host and target the rendered items with the classes from the [Anatomy](
-
+
The component renders into its light DOM, so regular selectors reach the rendered items. Its default styles give the host a height of `18.75rem`; override the height to size the viewport.
@@ -555,19 +860,20 @@ The {Platform} Virtual Scroll adds no key handlers. The host is a native scroll
| Page Up / Page Down | Scrolls by about one viewport. |
| Home / End | Scrolls to the start or the end of the collection. |
-The host has no `tabindex`. Browsers differ in whether a scroll container without focusable content can receive focus, so set `tabindex="0"` on the host when the items contain nothing focusable. Items scrolled out of view leave the DOM, so focus inside a removed item is lost.
+The host has no `tabindex`. Browsers differ in whether a scroll container without focusable content can receive focus, so set `tabindex="0"` on the host when the items contain nothing focusable. Focus inside an item does not survive that item leaving the rendered window, so move focus deliberately before it does.
### Screen Readers / ARIA
- The host has `role="list"`; the track, the content element, and the item wrappers have `role="presentation"`. Items that render `role="listitem"`, such as `igx-list-item`, are exposed as items of that list.
+- Inside a container that already provides list semantics, such as `igx-list`, set `role="presentation"` on the host so that the items are not nested in a second list.
- Map the `index` and `count` template variables to `aria-posinset` and `aria-setsize`.
- Give a focusable host an accessible name with `aria-label` or `aria-labelledby`.
-
+
- The track, the content element, and the item wrappers have `role="presentation"`. The host has no role: place it inside an element with a list role, such as `igc-list`, or give it `role="list"` when the items render `role="listitem"`.
- Map the `index` and `count` context properties to `aria-posinset` and `aria-setsize`.
@@ -603,7 +909,19 @@ The Virtual Scroll compares `data` by reference, so a change in place is not det
### Why does the scrollbar change size while I scroll?
-Items that have not rendered use `estimatedItemSize`, and the total size is corrected as items are measured. Set `estimatedItemSize` close to the average item size.
+Items that have not rendered use `estimatedItemSize`, and the total size is corrected as items are measured.
+
+
+
+Set `estimatedItemSize` close to the average item size.
+
+
+
+
+
+The average measured size then replaces the estimate for the items that are not measured yet, so the correction settles as you scroll. Set `estimatedItemSize` close to the average item size to make the first render land near the real content.
+
+
### Why do items drift out of place further down the list?
@@ -628,7 +946,7 @@ The Virtual Scroll measures items at runtime and creates its own scroll containe
| `igxForScrollContainer` | Not needed: the host is the scroll container |
| `scrollTo(index)` | `scrollToIndex(index, options)`, which returns a promise |
| `chunkLoad`, `chunkPreload` | `stateChange` |
-| `igxForRemote` with `totalItemCount` | `dataWindow` with `totalCount`, or `data` with `dataRequest` for append-only loading |
+| `igxForTotalItemCount` for remote data | `dataWindow` with `totalCount`, or `data` with `dataRequest` for append-only loading |
| `index`, `count`, `first`, `last`, `even`, `odd` | The same template variables |
The grids keep their own row and column virtualization; see [Grid Virtualization](../grid/virtualization.mdx).
@@ -638,7 +956,7 @@ The grids keep their own row and column virtualization; see [Grid Virtualization
## Known Limitations
- The {Platform} Virtual Scroll virtualizes one axis. Rows and columns that are both virtualized require a grid.
-- Items scrolled out of view are removed from the DOM together with their focus and internal state.
+- Item elements are reused as the window moves, so DOM state that the item template does not bind, such as a checkbox without a bound `checked`, shows on whichever item takes the element. Bind all item state, and write user changes back to the item.
@@ -664,6 +982,12 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs
+
+
+The {Platform} Virtual Scroll has no dependencies on other components and needs no theme of its own. `igniteui-react` brings in `igniteui-webcomponents` and `lit`, and the components in the item template need a theme stylesheet.
+
+
+
## Additional Resources
- [{ProductName} **Forums**]({ForumsLink})
@@ -674,14 +998,16 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs
- [List](../list.mdx) - Use the List for a short list, or as the container of a virtualized list.
+- [Data Grid](../grid/grid.mdx) - Use the Data Grid for tabular data with columns, sorting, or filtering.
- [Card](../card.mdx) - Use cards for a small set of rich items, or as items of a horizontal Virtual Scroll.
- [Virtual ForOf Directive](../for-of.mdx) - The directive-based virtualization used by existing lists.
-
+
- [List](../grids/list.mdx) - Use the List for a short list, or as the container of a virtualized list.
+- [Data Grid](../grids/data-grid.mdx) - Use the Data Grid for tabular data with columns, sorting, or filtering.
- [Card](./card.mdx) - Use cards for a small set of rich items, or as items of a horizontal Virtual Scroll.
@@ -694,6 +1020,9 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs
Items in the {Platform} Virtual Scroll can have different sizes, because each item is measured once it renders. Set `estimatedItemSize` close to the average item size so that the scrollbar is accurate before items are measured.
+
+ Once items are measured, their average replaces the estimate for the items that are not measured yet.
+
Call the {Platform} Virtual Scroll `scrollToIndex` method with the item index and optional `block` and `behavior` options. The method returns a promise that resolves when the corrected position is stable.
@@ -705,5 +1034,9 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs
The {Platform} Virtual Scroll supports append-only loading through the `igcDataRequest` event. Handle the event and assign a new array that includes the requested items to `data`.
+
+
+ The {Platform} Virtual Scroll supports append-only loading through the `onDataRequest` event. Handle the event and assign a new array that includes the requested items to `data`.
+
diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json
index e9bbfcbd2f..ef0a95b26c 100644
--- a/docs/xplat/src/content/en/toc.json
+++ b/docs/xplat/src/content/en/toc.json
@@ -2603,7 +2603,6 @@
},
{
"exclude": [
- "React",
"Blazor"
],
"name": "Virtual Scroll",
diff --git a/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx b/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx
index b5dbdd5708..06c76a3cca 100644
--- a/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx
+++ b/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx
@@ -1,25 +1,29 @@
---
title: "Virtual Scroll"
description: "Virtual Scroll は、ビューポート内のアイテムと少量のバッファーのみをレンダリングするコンポーネントであり、大量のリストでもスムーズにスクロールできます。"
-keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}"
-last_updated: "2026-09-17"
+keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}, 仮想スクロール, 仮想化, 仮想リスト, 大量リスト, 無限スクロール, リモート データ"
+last_updated: "2026-09-25"
license: MIT
mentionedTypes: ["VirtualScroll"]
-relatedComponents: ["List", "Card"]
+relatedComponents: ["List", "Grid", "Card"]
_language: ja
llms:
description: "{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。"
---
-import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro';
import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro';
import Sample from 'igniteui-astro-components/components/mdx/Sample.astro';
import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro';
+import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro';
import Faq from 'igniteui-astro-components/components/mdx/Faq.astro';
import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro';
+import { Image } from 'astro:assets';
+import virtualScrollAnatomy from '@xplat-images/anatomy-content-light/virtual-scroll-lt-a.png';
+import virtualScrollDo from '@xplat-images/virtual-scroll/virtual-scroll-do.png';
+import virtualScrollDoNot from '@xplat-images/virtual-scroll/virtual-scroll-do-not.png';
# Virtual Scroll コンポーネント
-{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。スクロールバーはコレクション全体に及ぶため、10 万件のアイテムを持つ仮想リストでも通常のリストと同じようにスクロールできます。
+{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。スクロールバーは常にコレクション全体の範囲を表すため、10 万件のアイテムを持つ仮想リストでも通常のリストと同じようにスクロールできます。
## ライブ デモ
@@ -29,7 +33,7 @@ import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro';
-
+
@@ -39,7 +43,27 @@ import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro';
{Platform} Virtual Scroll は、表示されているアイテムと設定可能なバッファーをレンダリングし、そのトラックはコレクション全体のスクロール範囲を保持します。
-{/*TODO: add the Virtual Scroll anatomy image and render it with the component.*/}
+
+
+
+
+1. ホスト: スクロール コンテナーです。固定の高さ (水平の場合は幅) によって、表示されるアイテムの数が決まります。
+2. トラック: コレクション全体の推定される長さに合わせてサイズが設定されるスペーサーです。これにより、スクロールバーがすべてのアイテムに及びます。
+3. コンテンツ要素: レンダリングされたアイテムのみを保持します。ビューポートの上にある、最初にレンダリングされたバッファー アイテムから始まり、そのサイズはレンダリングされたアイテムによって決まります。
+4. アイテム ラッパー: レンダリングされたアイテムごとに 1 つ存在し、アイテム テンプレートをホストします。サイズが測定されるのはこのボックスです。
+5. オーバー スキャン バッファー: ビューポートの各端を超えてレンダリングされる overScan 個のアイテム (デフォルトは 2) です。
@@ -52,7 +76,7 @@ igx-virtual-scroll — scrollable viewport (role="list")
-
+
```text
igc-virtual-scroll — scrollable viewport
@@ -116,7 +140,32 @@ virtualScroll.data = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${
-Virtual Scroll のホストには、垂直スクロールの場合は固定の高さ、水平スクロールの場合は固定の幅が必要です。コンテンツに合わせてサイズが拡大するホストには、埋めるべきビューポートがありません。
+
+
+[作業の開始](../general-getting-started.mdx) のトピックに従って {ProductName} をセットアップし、 をインポートして、アイテム テンプレートとデータを指定します。React ラッパーはモジュールの読み込み時に基になる要素を登録するため、登録の呼び出しは不要です。
+
+```tsx
+import { IgrVirtualScroll } from 'igniteui-react';
+import type { VirtualScrollItemContext } from 'igniteui-react';
+
+const items = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${i}` }));
+
+export function Employees() {
+ return (
+ ) => (
+