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

<nve-virtual-list>

Properties

PropertyAttributeDescriptionValues end none

Read-only exclusive requested end index; initially 0. The requested item count is end - start.

number
itemBuffer item-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.

number
itemCount item-count

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.

number
itemHeight item-height

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.

number
range none

Current immutable virtual-change request. Attach the listener before initialization, or read this property after attaching it and render once. Recheck identity before an asynchronous DOM update to discard obsolete work. Undefined for invalid geometry.

start none

Read-only inclusive requested start index; initially 0.

number

Events

EventDescription virtual-change

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.

virtual-scroll

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.

Slots

SlotDescription default

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.

Invoker Commands

CommandDescription --scroll-to-index

Scroll to the integer index in the source button's value, using scrollToIndex(). Missing, empty, fractional, or invalid numeric values have no effect.

Methods

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.

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.

CSS Properties

Css-propertyDescription --item-height

Output containing valid itemHeight in pixels. Slotted items use this fixed height automatically; custom item templates can also use it for their internal layout.

--scroll-height

Viewport height; default auto. Supply a bounded height for virtualization. A zero-height viewport requests [0, 0) and recovers when measurable.

--width

Container width. Defaults to 100%. MDN

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