Skip to main content
Neural UIv2.0.0Documentation
View v1 GitHub

VirtualList

Render a window of a large fixed-height list using stable item keys.

Category
Data and hierarchy
Import
@neural-ui/core/virtual-list
Selector
neu-virtual-list
import { NeuVirtualListComponent } from '@neural-ui/core/virtual-list';

Usage

Set itemKey to a stable unique string or number. itemSize is the actual row height in pixels; the Template must respect that height. visibleRows controls the viewport. rangeChange reports the rendered range, not a request to load data. Replace items when data changes; do not use an array index as a key for reorderable records.

Examples

Try this application-owned interaction. Its event handling and initial data are included in Code.

Examples
1 ยท Project 1
2 ยท Project 2
3 ยท Project 3
4 ยท Project 4
5 ยท Project 5
6 ยท Project 6
7 ยท Project 7
8 ยท Project 8

Events: 0

Try and configure

Change the public options, try the result and inspect the updated template. Code contains the complete executable implementation.

Try and configure
1 ยท Project 1
2 ยท Project 2
3 ยท Project 3
4 ยท Project 4
5 ยท Project 5
6 ยท Project 6
7 ยท Project 7
8 ยท Project 8

Events: 0

template.html
<neu-virtual-list
  [items]="items()"
  [itemKey]="itemKey"
  [visibleRows]="6"
  [itemSize]="48"
  (rangeChange)="record('rangeChange', $event)"
  [emptyLabel]="'No projects'"
><ng-template
    [neuVirtualItem]="items()"
    [neuVirtualItemKey]="itemKey"
    let-item
    let-index="index"
    ><div class="remaining-virtual-row">
      {{ index + 1 }} ยท {{ item.label }}
    </div></ng-template
  ></neu-virtual-list
>

State and events

Set itemKey to a stable unique string or number. itemSize is the actual row height in pixels; the Template must respect that height. visibleRows controls the viewport. rangeChange reports the rendered range, not a request to load data. Replace items when data changes; do not use an array index as a key for reorderable records.

Accessibility and keyboard

Focus the scroll region and use normal browser scrolling. Interactive controls inside a Template retain their native keyboard behavior.

Key
Action
Tab Reach the scroll region and focusable controls rendered by item templates.
ArrowUp / ArrowDown Use native scrolling when the scroll region has focus.
PageUp / PageDown Scroll a page at a time in the focused region.

API

Inputs, models and Outputs are extracted from the installed Core package. Named public types link to their definitions. Templates below include executable examples.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name
Type
Default
Template binding
Description
emptyLabelstring'No results'[emptyLabel]Label for empty collection. Translate it for your application.
itemKey(item: T) => KRequired[itemKey]Function returning a stable unique key for each virtual row.
itemsreadonly T[][][items]Applied item collection. Stable keys and accessors identify entries; the component does not mutate the array.
itemSizenumber48[itemSize]Fixed row height in pixels. Template content must fit this height.
visibleRowsnumber10[visibleRows]Number of rows determining the virtual viewport height.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name
Payload
Template binding
Description
rangeChangeNeuVirtualListRange(rangeChange)="onRangeChange($event)"Current visible virtual viewport range.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

Name
Mechanism
Contract
NeuVirtualItemDirectiveView example Public template directive (entrypoint)ng-template[neuVirtualItem]

Each example demonstrates a different template. Switch between Demo and Code to inspect its implementation, imports and state.

NeuVirtualItemDirective

NeuVirtualItemDirective

NeuVirtualItemDirective
1 ยท Project 1
2 ยท Project 2
3 ยท Project 3
4 ยท Project 4
5 ยท Project 5
6 ยท Project 6
7 ยท Project 7
8 ยท Project 8

Events: 0

Public Types

Open a type to inspect its definition and interface fields.

Styles and tokens

Use the supported public tokens listed below. Surrounding layout belongs to your application; validate the result in light and dark modes and narrow containers.

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token
Purpose here
Other impact
Default / fallback
--neu-text-muted Secondary labels and supporting content Shared by other Core consumers; scope the override. #475569