npm package: @ruc-lib/virtual-scroll
Description: 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.
Latest version: 4.0.0

# 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
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

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
### 1. Import the Component
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
}
```

### 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.

```html
<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.

```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);
}
```

## 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!