DATABETA

VirtualScroller

Deterministic fixed-size windowing for large vertical and horizontal collections with Signals, typed templates and lazy ranges.

10,000+ recordsSSR safeHeadless ready

GET STARTED

Import

Import the canonical standalone component and only the template directives you use.

import {
  NeuralVirtualScroller,
  NeuralVirtualScrollerItemTemplate,
  NeuralVirtualScrollerEmptyTemplate,
  NeuralVirtualScrollerLoadingTemplate,
} from '@neural-ng/core/virtual-scroller';

@Component({
  imports: [
    NeuralVirtualScroller,
    NeuralVirtualScrollerItemTemplate,
    NeuralVirtualScrollerEmptyTemplate,
    NeuralVirtualScrollerLoadingTemplate,
  ],
})

10,000 records

Only the visible window and overscan exist in the DOM. The end index is always exclusive.

Visible 1–6 · rendered 1–9

#1Agent task 00001ResearchReady

#2Agent task 00002BuildRunning

#3Agent task 00003ReviewQueued

#4Agent task 00004ResearchReady

#5Agent task 00005BuildRunning

#6Agent task 00006ReviewQueued

#7Agent task 00007ResearchReady

#8Agent task 00008BuildRunning

#9Agent task 00009ReviewQueued

Horizontal orientation

The same range engine windows a horizontal card rail without changing its event contract.

Agent task 00001Research · 1

Agent task 00002Build · 2

Agent task 00003Review · 3

Agent task 00004Research · 4

Agent task 00005Build · 5

Controlled position and imperative scrolling

[(first)], native scrolling and imperative methods remain synchronized.

First: 1

1Agent task 00001

2Agent task 00002

3Agent task 00003

4Agent task 00004

5Agent task 00005

6Agent task 00006

Lazy ranges and loading

lazyLoad emits each distinct overscanned range for race-safe data sources.

Requested [0, 8) · visible [0, 5)

1Agent task 00001

2Agent task 00002

3Agent task 00003

4Agent task 00004

5Agent task 00005

6Agent task 00006

7Agent task 00007

8Agent task 00008

Typed empty and loading templates

State templates receive both the implicit localized label and its named label property.

No queued work

[object Object]

Streaming records

Unstyled and typed slots

Windowing, dimensions and list semantics remain while consumer classes own every visual choice.

1Agent task 00001Ready

2Agent task 00002Running

3Agent task 00003Queued

4Agent task 00004Ready

5Agent task 00005Running

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

rangeChangeNeuralVirtualScrollerRangeEvent

Rendered or visible window changed.

lazyLoadNeuralVirtualScrollerRangeEvent

New lazy range requested.

scrolledNeuralVirtualScrollerScrollEvent

Native scroll with offset and range.

firstChangenumber

Generated 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.

rootviewportcontentspacerBeforeitemsitemspacerAfteremptyloading

Public types

NeuralVirtualScrollerOrientationNeuralVirtualScrollerScrollBehaviorNeuralVirtualScrollerRangeEventNeuralVirtualScrollerScrollEventNeuralVirtualScrollerTrackBy<T>NeuralVirtualScrollerItemContext<T>NeuralVirtualScrollerStateContextNeuralVirtualScrollerClasses

VIRTUALSCROLLER

Design tokens

Component tokens customize its surface without changing deterministic structural dimensions.

Component tokens

--neural-virtual-scroller-color

Component foreground color.

--neural-virtual-scroller-background

Component background surface.

--neural-virtual-scroller-border

Component border shorthand.

--neural-virtual-scroller-radius

Component corner radius.

--neural-virtual-scroller-shadow

Component box shadow.

--neural-virtual-scroller-item-padding

Item internal spacing.

Primary

Surface

VirtualScroller

Import

10,000 records

Horizontal orientation

Controlled position and imperative scrolling

Lazy ranges and loading

Typed empty and loading templates

Unstyled and typed slots

Accessibility

Region and list semantics

Keyboard and focus

Collection position metadata

Reduced motion

SSR and responsibility boundary

API

Component

Inputs and model

Events

Methods

Typed templates and class slots

Public types

Design tokens

Component tokens