Fixed-height virtualization with native vertical host scrolling. Consumers own data, templates, and selection: render each virtual-change request by replacing or reordering items in the default slot. Native slot changes position the rendered window automatically. Consumers own item navigation and can override tabindex. For horizontal scrolling, size the list to its content width and wrap it in a horizontal scroll container. Missing, empty, or invalid required geometry hides content and exposes an empty range. Development diagnostics identify invalid configurations; valid values restore rendering. Variable heights, row groups, detail panels, segmented scrolling, and column virtualization aren't supported.
<nve-virtual-list id="demo-list" item-count="10000" item-height="44" style="--scroll-height: 300px"></nve-virtual-list>
<script type="module">
import "@nvidia-elements/foundations/virtual-list/define.js";
const list = document.querySelector("#demo-list");
const data = Array.from({ length: 10000 }, (_, i) => "Item " + i);
function draw(range) {
list.innerHTML = data
.slice(range.start, range.end)
.map((item) => "<div>" + item + "</div>")
.join("");
}
await list.updateComplete;
list.addEventListener("virtual-change", (event) => draw(event.detail));
draw(list.range);
</script>
Installation
<script type="module">
import '@nvidia-elements/foundations/virtual-list/define.js';
</script>
<nve-virtual-list id="demo-list" item-count="10000" item-height="44" style="--scroll-height: 300px"></nve-virtual-list>
<script type="module">
import "@nvidia-elements/foundations/virtual-list/define.js";
const list = document.querySelector("#demo-list");
const data = Array.from({ length: 10000 }, (_, i) => "Item " + i);
function draw(range) {
list.innerHTML = data
.slice(range.start, range.end)
.map((item) => "<div>" + item + "</div>")
.join("");
}
await list.updateComplete;
list.addEventListener("virtual-change", (event) => draw(event.detail));
draw(list.range);
</script>
nve api.get nve-virtual-list
Item geometry
Required total number of items: a nonnegative safe integer. Total height (itemCount * itemHeight) cannot exceed 16,000,000 CSS pixels.Supports property assignments before the first update. For deliberate imperative configuration without attributes, narrowly suppress @nvidia-elements/lint/no-invalid-virtual-list and explain the assignments; don't use invalid placeholder attributes.
ItemCount Description number Required finite item height greater than zero, in CSS pixels. The viewport sizes slotted items to exactly this height, including borders, and clips overflow.Keep custom item internals within this height and avoid gaps between items.
ItemHeight Description number Viewport height; default auto. Supply a bounded height for virtualization. A zero-height viewport requests [0, 0) and recovers when measurable.
Rendering
Requests [start, end) through immutable detail: { start, end, count }. count is the total dataset size. Range properties update before dispatch. Fires initially for valid geometry, including an empty dataset, then only when (start, end, count) changes. Slot changes don't request another range. Bubbles across shadow boundaries.
Elements for the requested [start, end) range. Replace or reorder assigned elements for a new window; reusing the same elements with only content or property updates cannot signal a new window. Content stays hidden while a different window awaits changed assignments. Asynchronous consumers must discard obsolete work before changing DOM. In grids, render direct nve-grid-row children and supply logical aria-rowindex values and total aria-rowcount. The wrapper adds no list or region role, and the spacer stays outside the accessibility tree.
Scheduled rendering
Scheduled rendering ignores obsolete range requests. Use this pattern to update a list after asynchronous work.
<nve-virtual-list id="scheduled-viewport" item-count="10000" item-height="44" style="--scroll-height: 240px"></nve-virtual-list>
<script type="module">
import "@nvidia-elements/foundations/virtual-list/define.js";
const list = document.querySelector("#scheduled-viewport");
const data = Array.from({ length: 10000 }, (_, i) => "Item " + i);
function draw(range) {
queueMicrotask(() => {
if (list.range !== range) return;
list.innerHTML = data
.slice(range.start, range.end)
.map((item) => "<div>" + item + "</div>")
.join("");
});
}
await list.updateComplete;
list.addEventListener("virtual-change", (event) => draw(event.detail));
draw(list.range);
</script>
Buffer
Extra items on each side of the viewport. Must be a nonnegative safe integer; invalid values produce a diagnostic and use the default of 2.
ItemBuffer Description number Reports detail: { scrollTop, direction } when vertical position changes. Direction is up or down relative to the previous notification. Coalesces updates per animation frame, including programmatic scrolling; unchanged positions emit no event. Bubbles across shadow boundaries. Native scroll and scrollend remain available on the host.
MethodSignaturesDescription scrollToIndex scrollToIndex(index: number, behavior?: ScrollBehavior): void
Scroll the nearest edge of an integer index into view. Clamp finite integer indices to dataset bounds; ignore fractional indices, NaN, infinity, and empty datasets.Items taller than the viewport align to their start. The default is immediate and interrupts smooth scrolling, even when CSS sets scroll-behavior: smooth. Pass an explicit ScrollBehavior to override it.
Scroll to the integer index in the source button's value, using scrollToIndex(). Missing, empty, fractional, or invalid numeric values have no effect.
Native command buttons jump to an item by index. Use these controls to navigate long lists.
<div nve-layout="row gap:sm pad-bottom:md">
<nve-button commandfor="command-viewport" command="--scroll-to-index" value="500">Scroll to 500</nve-button>
<nve-button commandfor="command-viewport" command="--scroll-to-index" value="0">Scroll to first</nve-button>
<nve-button commandfor="command-viewport" command="--scroll-to-index" value="9999">Scroll to last</nve-button>
</div>
<nve-virtual-list id="command-viewport" item-count="10000" item-height="44" style="--scroll-height: 250px"></nve-virtual-list>
<script type="module">
import "@nvidia-elements/core/button/define.js";
import "@nvidia-elements/foundations/virtual-list/define.js";
const list = document.querySelector("#command-viewport");
const data = Array.from({ length: 10000 }, (_, i) => "Item " + i);
function draw(range) {
list.innerHTML = data
.slice(range.start, range.end)
.map((item) => "<div>" + item + "</div>")
.join("");
}
await list.updateComplete;
list.addEventListener("virtual-change", (event) => draw(event.detail));
draw(list.range);
</script>
Scroll to 500 Scroll to first Scroll to last
Refresh
MethodSignaturesDescription refresh refresh(): void
Recalculate geometry and range from the current viewport and scroll position. Scrolling, resizing, and valid configuration changes refresh automatically. Emits no event when (start, end, count) stays unchanged.
Data grid
nve-grid-header, nve-grid-row, nve-virtual-list, and nve-grid-placeholder elements.
A fixed-height viewport keeps 10,000 logical rows responsive with bounded DOM size. Use virtualization for large datasets with fixed-height rows to keep scrolling responsive.
<nve-grid id="virtual-jobs" aria-label="Training jobs" aria-rowcount="10002" stripe>
<nve-grid-header aria-rowindex="1">
<nve-grid-column>Job</nve-grid-column>
<nve-grid-column>Status</nve-grid-column>
<nve-grid-column>Queue</nve-grid-column>
<nve-grid-column>Owner</nve-grid-column>
</nve-grid-header>
<nve-virtual-list tabindex="-1" item-count="10000" item-height="44" style="--scroll-height: 400px"></nve-virtual-list>
<nve-grid-footer aria-rowindex="10002">10,000 training jobs</nve-grid-footer>
</nve-grid>
<template id="virtual-job-row">
<nve-grid-row>
<nve-grid-cell></nve-grid-cell><nve-grid-cell></nve-grid-cell>
<nve-grid-cell></nve-grid-cell><nve-grid-cell></nve-grid-cell>
</nve-grid-row>
</template>
<script type="module">
import "@nvidia-elements/core/grid/define.js";
import "@nvidia-elements/foundations/virtual-list/define.js";
const list = document.querySelector("#virtual-jobs > nve-virtual-list");
const template = document.querySelector("#virtual-job-row");
function draw({ start, end }) {
const rows = Array.from({ length: end - start }, (_, localIndex) => {
const index = start + localIndex;
const row = template.content.firstElementChild.cloneNode(true);
row.ariaRowIndex = String(index + 2);
const values = ["Job " + index, "Running", "Queue " + (index % 5), "Team " + (index % 10)];
Array.from(row.children).forEach((cell, column) => (cell.textContent = values[column]));
return row;
});
list.replaceChildren(...rows);
}
list.addEventListener("virtual-change", (event) => draw(event.detail));
draw(list.range);
</script>
Release Status
All elements and features go through 3 phases of stability, pre-release, beta and stable.
pre-release Docs Preview API Documentation Fully Themeable
beta Robust unit test coverages Passed API Review Passed Designer VQA Review Included in library package stable No known outstanding AA WCAG issues No known outstanding performance issues Adapts to different screen/container sizes No breaking API changes for at least 90 days