ruclib-virtual-scroll

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.

Installation guide

To use the Virtual Scroll component, you can install the entire RUC library or just this specific component.

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the VirtualScroll component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

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

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibVirtualScrollComponent:

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
}

2. Use the Component

In your component's template, use the <uxp-ruclib-virtual-scroll> selector and pass the configuration object to the rucInputData input and the data array to the dataSource input.

<uxp-ruclib-virtual-scroll 
    [rucInputData]="virtualScrollConfig"
    [customTheme]="customTheme">
    <!-- Put your component here -->
</uxp-ruclib-virtual-scroll>

API Reference

Component Inputs

| Input | Type | Description | |----------------|----------------------|-------------------------------------------------------| | rucInputData | virtualScrollConfig| The main configuration object for the Virtual Scroll. | | customTheme | string | An optional CSS class for custom theming. |

Component Outputs

| Output | Type | Description | |---------|-----------|-----------------------------------------------| |---------|-----------| User can see the UI with virtual scroll data |

virtualScrollConfig

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.

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:

.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);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Virtual Scroll component. If you have any feedback or suggestions, please let us know!