NVIDIA Elements Patterns Elements Foundations Integrations GitHub System Themes

Virtual List

beta:  2.27.0 Coverage: unknown Bundle: 10kb Lighthouse: 100 Axe Core Released: 0.0.0
Overview API Examples

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.

Installation

CLI / MCP / CDN

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.

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

Scrolling

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.

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.

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
Getting Started Overview Installation CLI MCP Skills Lint What’s New GitHub Patterns Overview Agent Authentication Browse Chat Code Dashboard Editor Empty States Heatmap Keyboard Shortcut Logging Media Navigation Onboarding Panel Responsive Search Subheader Trend Elements Overview Accordion Alert Avatar Badge Breadcrumb Button Button Group Card Chat Message Checkbox Codeblock Color Combobox Copy Button Dashboard Datagrid Getting Started Integrations Column Action Column Alignment Column Fixed Column width Container Card Display Settings Footer Heatmap Keynav Multi Select Pagination Panel Detail Panel Grid Performance Placeholder Row Action Row Groups Row Sort Scroll Height Single Select Stripe Date Datetime Dialog Divider Dot Drag Handle Drawer Dropdown Dropdown Group Dropzone File Format Bytes Datetime Number Relative Time Truncate Forms Getting Started Validation Actions Control Gauge Ghost Icon Icon Button Iframe Input Input Group Joystick List Logo Markdown Markdown CSS Media Controller Pause Button Playback Rate Select Loop Button Mute Button Media PiP Button Seek Button Time Range Volume Range Full-screen Button Menu Month Monaco Input Diff Input Monaco Editor Diff Editor Problems Notification Page Page Header Page Loader Pagination Progressive Filter Chip Progress Bar Progress Dot Progress Ring Password Preferences Input Pulse Radio Range Resize Handle Scroll Box Search Select Skeleton Sort Button Sparkline Star Rating Steps Switch Tabs Tag Text Textarea Time Toast Toggletip Toolbar Tooltip Tree Viewport Viewport Gridlines Minimap Zoom Range Virtual List Week Workspace Foundations Overview Typography Iconography Themes Design Tokens Size & Space Objects Interactions Support Status Color Animation Fonts Layers Custom Layout Horizontal Vertical Grid Popovers i18n Visualization View Transitions DESIGN.md Integrations Getting Started Angular Bundles CDN Custom Elements Eleventy Golang HTMX + Go Hugo Import Maps Lit Lit Library MCP Apps NextJS Nuxt Pi Preact React SolidJS Sphinx Svelte TypeScript Vue About Changelog Metrics Support Accessibility Contributions Requests Migration Sitemap Labs Responsive Layout Viewport Container Patterns Forms Internal API Design Guidelines Properties & Attributes Slots Registration CustomEvents Stateless Composition Styles Packaging Glossary Logs Guidelines Agent Harness Agent Tooling Agent Ownership Documentation Examples TypeScript Testing Unit Testing Accessibility Testing Lighthouse Testing SSR Testing Visual Testing Troubleshooting Component Creation Examples All Examples