VirtualScroller
Deterministic fixed-size windowing for large vertical and horizontal collections with Signals, typed templates and lazy ranges.
GET STARTED
Import
Import the canonical standalone component and only the template directives you use.
10,000 records
Only the visible window and overscan exist in the DOM. The end index is always exclusive.
Horizontal orientation
The same range engine windows a horizontal card rail without changing its event contract.
Controlled position and imperative scrolling
[(first)], native scrolling and imperative methods remain synchronized.
Lazy ranges and loading
lazyLoad emits each distinct overscanned range for race-safe data sources.
Typed empty and loading templates
State templates receive both the implicit localized label and its named label property.
Unstyled and typed slots
Windowing, dimensions and list semantics remain while consumer classes own every visual choice.
VIRTUALSCROLLER
Accessibility
Region and list semantics
The root is a named region. Its viewport is a native list and each rendered record is a listitem.
Keyboard and focus
The viewport remains natively focusable and scrollable. Page Up, Page Down, Home, End and platform scrolling continue to work without custom key interception.
Collection position metadata
Every rendered item exposes aria-posinset and the full collection length through aria-setsize, even though offscreen items are absent.
Reduced motion
Smooth programmatic scrolling falls back to immediate native scrolling when the user requests reduced motion.
SSR and responsibility boundary
The initial range is deterministic during SSR and hydration. Selection, editing and variable-height measurement intentionally belong to composing components or application code.
VIRTUALSCROLLER
API
Component
NeuralVirtualScroller<T> Standalone component with selector neural-virtual-scroller. VirtualScrollerComponent remains only as a deprecated compatibility alias.
Inputs and model
| Name | Type | Default | Purpose |
|---|---|---|---|
| items | readonly T[] | [] | Immutable source collection. |
| itemSize | number | 48 | Fixed item size on the scroll axis. |
| viewportSize | number | 320 | Viewport size on the scroll axis. |
| overscan | number | 3 | Extra rendered items around the viewport. |
| orientation | 'vertical' | 'horizontal' | 'vertical' | Scroll axis. |
| first | model<number> | 0 | First visible item index. |
| lazy | boolean | false | Emits lazyLoad for each new range. |
| loading | boolean | false | Displays the loading layer. |
| emptyMessage | string | 'No items found' | Empty-state label. |
| loadingMessage | string | 'Loading items' | Loading-state label. |
| ariaLabel | string | 'Virtual list' | Region and list name. |
| tabindex | number | 0 | Native viewport tab order. |
| trackBy | NeuralVirtualScrollerTrackBy<T> | null | null | Stable item identity. |
| unstyled | boolean | false | Removes NeuralNg visual classes. |
| virtualScrollerClass | string | '' | Additive root class. |
| classes | NeuralVirtualScrollerClasses | {} | Typed class slots. |
Events
rangeChangeNeuralVirtualScrollerRangeEventRendered or visible window changed.
lazyLoadNeuralVirtualScrollerRangeEventNew lazy range requested.
scrolledNeuralVirtualScrollerScrollEventNative scroll with offset and range.
firstChangenumberGenerated model output.
Methods
scrollToIndex(index, behavior?)Scrolls to a clamped item index.
scrollToOffset(offset, behavior?)Scrolls to a non-negative pixel offset.
Typed templates and class slots
neuralVirtualScrollerItem, neuralVirtualScrollerEmpty and neuralVirtualScrollerLoading preserve template inference.
rootviewportcontentspacerBeforeitemsitemspacerAfteremptyloadingPublic types
NeuralVirtualScrollerOrientationNeuralVirtualScrollerScrollBehaviorNeuralVirtualScrollerRangeEventNeuralVirtualScrollerScrollEventNeuralVirtualScrollerTrackBy<T>NeuralVirtualScrollerItemContext<T>NeuralVirtualScrollerStateContextNeuralVirtualScrollerClassesVIRTUALSCROLLER
Design tokens
Component tokens customize its surface without changing deterministic structural dimensions.
Component tokens
--neural-virtual-scroller-colorComponent foreground color.
--neural-virtual-scroller-backgroundComponent background surface.
--neural-virtual-scroller-borderComponent border shorthand.
--neural-virtual-scroller-radiusComponent corner radius.
--neural-virtual-scroller-shadowComponent box shadow.
--neural-virtual-scroller-item-paddingItem internal spacing.