🔄 ngx-smart-scroll

A blazing-fast, fully customizable infinite scroll directive for Angular.
Supports both vertical and horizontal scrolling with precision configuration, directional triggers, container targeting, and debounce/throttle controls — all baked into a single lightweight package.

🚀 Features

• ✅ Vertical & horizontal scroll support
• ✅ Works with container or window scroll targets
• ✅ Supports offsetPx and percentThreshold triggers
• ✅ Detect forward, backward, or both scroll directions
• ✅ Debounce & throttle built-in
• ✅ Emits rich ScrollInfo metadata (scroll positions, direction)
• ✅ Lightweight and zone-optimized

📦 Installation

npm install ngx-smart-scroll

🧠 Usage

✅ Basic Vertical Scroll

<div
  class="size-[40rem] p-4 bg-red-400 overflow-auto flex flex-col gap-4"
  ngx-smart-scroll
  [config]="scrollConfig"
  (scrolled)="onScrolled($event)">
  
  <div class="bg-green-200 w-full h-16">Data</div>
  <!-- More content -->
</div>

import { InfiniteScrollConfig, ScrollDirection } from 'ngx-smart-scroll';

scrollConfig: InfiniteScrollConfig = {
  percentThreshold: 80,
  debounceTime: 50,
  scrollDirection: ScrollDirection.VERTICAL,
};

OR

scrollConfig: InfiniteScrollConfig={
  scrollDirection:ScrollDirection.VERTICAL,
  strictPositions:['40%','60%','90%']
}

🆕 strictPositions (Advanced Precision Mode)

Use strictPositions when you want scroll events to trigger only at specific thresholds — such as exactly 90% scrolled or 400px.

Unlike offsetPx or percentThreshold, which fire as soon as the threshold is crossed, strictPositions only fires once per configured position, ensuring no repeated triggering.

Example

scrollConfig: InfiniteScrollConfig={
  scrollDirection:ScrollDirection.VERTICAL,
  strictPositions:['40%','60%','90%','400px']
}

• ✅ Event triggers once when scroll reaches 40%,60%,400px

🧪 Want Offset-Based Triggers?

Use one of:

offsetPx: 200
percentThreshold: 85

These will continuously trigger as the scroll crosses the offset, unlike strictPositions.

➡️ Horizontal Scroll

<div
  class="size-[40rem] p-4 bg-red-400 overflow-auto flex gap-4"
  ngx-smart-scroll
  [config]="scrollConfig"
  (scrolled)="onScrolled($event)">
  
  <div class="bg-green-200 h-[100rem] w-16">Data</div>
  <!-- More horizontal content -->
</div>

scrollConfig: InfiniteScrollConfig = {
  percentThreshold: 80,
  debounceTime: 50,
  scrollDirection: ScrollDirection.HORIZONTAL,
};

🧩 Configuration

InfiniteScrollConfig

| Property | Type | Default | Description | |--------------------|-------------------------------------------|--------------|------------------------------------------| | scrollDirection | VERTICAL | HORIZONTAL | VERTICAL | Scroll axis to observe | | scrollTarget | string | HTMLElement | ElementRef | Host element | Scroll container to observe | | offsetPx | number | null | Trigger scroll when within X px from end | | percentThreshold | number (0–100) | 100 | Trigger scroll when threshold reached | | scrollType | FORWARD | BACKWARD | ALL | ALL | Scroll direction(s) to trigger from | | debounceTime | number (ms) | 100 | Debounce scroll event frequency | | throttleTime | number (ms) | 0 | Throttle time between emits | | disable | boolean | false | Disable scroll events | | strictPositions | string[] | [] | target points |

📤 Emitted Event

The (scrolled) event returns a rich payload of type:

interface ScrollInfo {
  direction: ScrollType;
  coords: ScrollCoord;
}

interface ScrollCoord {
  scrollTop: number;
  scrollHeight: number;
  clientHeight: number;
  scrollLeft: number;
  scrollWidth: number;
  clientWidth: number;
}

Example:

onScrolled(event: ScrollInfo) {
  console.log('Scrolled:', event.direction);
  console.log('Scroll Position:', event.coords.scrollTop);
}

🔧 Advanced Use Cases

Targeting a Custom Scroll Container

scrollConfig: InfiniteScrollConfig = {
  scrollTarget: '#custom-container',
  offsetPx: 300
};

<div id="custom-container" class="overflow-auto h-[300px]">
  <div ngx-smart-scroll [config]="scrollConfig" (scrolled)="loadMore()">
    <!-- content -->
  </div>
</div>

🔒 Angular Compatibility

"peerDependencies": {
  "@angular/core": ">=14.0.0 <20.0.0",
  "@angular/common": ">=14.0.0 <20.0.0"
}

Tested with Angular v14 through v19.

🧪 Roadmap

• [ ] Virtual scroll support
• [ ] Auto-unsubscribe on *ngIf teardown
• [ ] Infinite scroll loader template
• [ ] RxJS event stream exposure (as observable)
• [ ] Mobile-friendly enhancements

✅ License

MIT License. Created by Vishnu kumar.

🔗 Connect with Me

Feel free to connect with me on social media:

• Portfolio
• GitHub
• LinkedIn
• PlayStore