Virtual scroll, often referred to as "virtualized lists" or "windowing," is a technique used to efficiently display large, scrollable lists of items in a user interface.
npm install @ruc-lib/virtual-scrollbash
npm install @uxpractice/ruc-lib
`
$3
If you only need the VirtualScroll component:
For Angular 15:
`bash
npm install @ruc-lib/virtual-scroll@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
`
For Angular 16:
`bash
npm install @ruc-lib/virtual-scroll@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
`
For Angular 17:
`bash
npm install @ruc-lib/virtual-scroll@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
`
For Angular 18:
`bash
npm install @ruc-lib/virtual-scroll@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
`
For Angular 19:
`bash
npm install @ruc-lib/virtual-scroll@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
`
For Angular 20:
`bash
npm install @ruc-lib/virtual-scroll@4.0.0
`
> Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.
Version Compatibility
Please ensure you install the correct version of @ruc-lib/virtual-scroll based on your Angular version.
| Angular Version | Compatible @ruc-lib/virtual-scroll Version |
|--------------------|--------------------------------------------------|
| 15.x.x | npm install @ruc-lib/virtual-scroll@^3.2.0 |
| 16.x.x | npm install @ruc-lib/virtual-scroll@^3.2.0 |
| 17.x.x | npm install @ruc-lib/virtual-scroll@^4.0.0 |
| 18.x.x | npm install @ruc-lib/virtual-scroll@^4.0.0 |
| 19.x.x | npm install @ruc-lib/virtual-scroll@^4.0.0 |
| 20.x.x | npm install @ruc-lib/virtual-scroll@^4.0.0 |
Usage
$3
In your Angular component file (e.g., app.component.ts), import the RuclibVirtualScrollComponent:
`typescript
import { Component } from '@angular/core';
// For Complete Library
import { RuclibVirtualScrollComponent } from '@uxpractice/ruc-lib/virtual-scroll';
// For Individual Package
import { RuclibVirtualScrollComponent } from '@ruc-lib/virtual-scroll';
@Component({
selector: 'app-root',
imports: [RuclibVirtualScrollComponent],
templateUrl: './app.component.html',
})
export class AppComponent {
// Component code here
}
`
$3
In your component's template, use the selector and pass the configuration object to the rucInputData input and the data array to the dataSource input.
`html
[customTheme]="customTheme">
API Reference
$3
| Input | Type | Description |
|----------------|----------------------|-------------------------------------------------------|
| rucInputData | virtualScrollConfig| The main configuration object for the Virtual Scroll. |
| customTheme | string | An optional CSS class for custom theming. |
$3
| Output | Type | Description |
|---------|-----------|-----------------------------------------------|
|---------|-----------| User can see the UI with virtual scroll data |
$3
This is the main configuration object for the Virtual Scroll component.
| Property | Type | Description |
|---------------------------|-------------------------------------|-----------------------------------------------------------------------|
| viewportWidth | string | Width of the viewport in percentage of Virtual Scroll. |
| viewportHeight | boolean | Height of the viewport in percentage of Virtual Scroll. |
| itemSize | number | Size of the element appeared in UI |
| backToTopIcon | string | material icon for back to top button. |
| backToTopLabel | string | Configure the label for back to top button. |
| iconColor | 'primary' \| 'accent' \| 'warn' | Change the color of the back to top button. |
| isLoad | boolean | It should be true if user want scroll at the end when data loads. |
| isBackToTopIcon | boolean | If value of this is true, back to top icon will be enabled. |
| thumbColor | string | User can customize thumb color. |
| trackColor | string | User can customize track color. |
Example Configuration
Here's an example of how to configure the Virtual Scroll component in your component's TypeScript file.
`typescript
import { Component } from '@angular/core';
// For Complete Library
import { RucVirtualScrollInput } from '@uxpractice/ruc-lib/virtual-scroll';
// For Individual package
import { RucVirtualScrollInput } from '@ruc-lib/virtual-scroll';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
})
export class AppComponent {
virtualScrollConfig: RucVirtualScrollInput = {
viewportWidth: '70%',
viewportHeight: '50vh',
itemSize: 40,
backToTopIcon: 'arrow_upward', // user can update accordingly and it should be material icon
backToTopLabel: 'Move to Top', // user can update accordingly
iconColor: 'primary', // 'accent', 'warn'
isLoad: true,
isBackToTopIcon: true,
thumbColor: 'green', //ex. '#888'
trackColor: 'lightgreen', //ex. '#fff'
};
}
`
> ⚠️ IMPORTANT: Custom Theme Usage in Angular Material
When implementing custom themes, such as:
`scss
.custom-theme-1 {
@include angular-material-theme($custom-theme);
}
// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
@include angular-material-theme($custom-theme);
@include mat.typography-level($theme-custom-typography-name, body-1);
}
``