ngx-scroll-to

A lightweight Angular standalone directive that scrolls a host element when input values change.

Use it when you want declarative scrolling with simple inputs for horizontal and vertical positions.

Features

• Standalone directive ([ngx-scrollTo])
• Reactive: automatically scrolls whenever inputs change
• Supports start, end, or numeric pixel values
• Smooth scrolling built in
• Can scroll horizontally, vertically, or both

Installation

npm install ngx-scroll-to

Import and Setup

Standalone Component (recommended)

import { Component } from '@angular/core';
import { NgxScrollTo } from 'ngx-scroll-to';

@Component({
   selector: 'app-demo',
   standalone: true,
   imports: [NgxScrollTo],
   template: `
      <div
         ngx-scrollTo
         [horizontal]="xPos"
         [vertical]="yPos"
         style="overflow: auto; width: 320px; height: 180px;"
      >
         <div style="width: 1200px; height: 1200px;"></div>
      </div>
   `,
})
export class DemoComponent {
   xPos: number | 'start' | 'end' | undefined = 'start';
   yPos: number | 'start' | 'end' | undefined = 'start';
}

NgModule-based App

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { NgxScrollTo } from 'ngx-scroll-to';

@NgModule({
   declarations: [AppComponent],
   imports: [BrowserModule, NgxScrollTo],
   bootstrap: [AppComponent],
})
export class AppModule {}

Directive API

Selector: [ngx-scrollTo]

Inputs

| Input | Type | Default | Description | |---|---|---|---| | horizontal | number \| 'start' \| 'end' \| undefined | undefined | Horizontal scroll target for scrollLeft. | | vertical | number \| 'start' \| 'end' \| undefined | undefined | Vertical scroll target for scrollTop. |

Input Value Semantics

For each axis:

• 'start' -> 0
• 'end' -> maximum content extent (scrollWidth for horizontal, scrollHeight for vertical)
• number -> exact pixel value passed to Element.scrollTo
• undefined -> axis is not explicitly set in that update

Behavior Details

The directive listens to input changes using Angular signals and runs scrollTo whenever either horizontal or vertical changes.

Important notes:

• Scrolling is always smooth (behavior: 'smooth').
• If only one axis is provided, only that axis is intended to change.
• The host element must be scrollable (overflow: auto or overflow: scroll) and have constrained size.

Usage Examples

Scroll to top-left

<div ngx-scrollTo [horizontal]="'start'" [vertical]="'start'"></div>

Scroll to bottom-right

<div ngx-scrollTo [horizontal]="'end'" [vertical]="'end'"></div>

Scroll to exact pixel positions

<div ngx-scrollTo [horizontal]="320" [vertical]="640"></div>

Update scroll reactively from code

goToSection(index: number) {
   this.vertical = index * 400;
}

goToStart() {
   this.horizontal = 'start';
   this.vertical = 'start';
}

License

MIT