TheJLifeX/ngx-scroll-position-restoration

Scroll position restoration in Angular.

NgxScrollPositionRestoration

Scroll position restoration in Angular.

The library supports scroll position restoration on:

• Any scrollable element
• Lazy loading content
• Named router-outlets (multiple router-outlets)
• Child routes (nested router-outlets)
• Backward and forward navigation

View the demo

Installation

npm install ngx-scroll-position-restoration --save

Usage

Step 01: Import the NgxScrollPositionRestorationModule to your root module.

app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

// Import NgxScrollPositionRestorationModule
import { NgxScrollPositionRestorationModule } from 'ngx-scroll-position-restoration';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AppRoutingModule,
    NgxScrollPositionRestorationModule.forRoot() // Import NgxScrollPositionRestorationModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Step 02: In your AppRoutingModule disable the Angular default scroll position restoration.

app-routing.module.ts

import { NgModule } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';

const routes: Routes = [];

@NgModule({
  imports: [
    RouterModule.forRoot(
      routes,
      {
        scrollPositionRestoration: 'disabled' // Here
      }
    )
  ],
  exports: [RouterModule]
})
export class AppRoutingModule { }

Optional Step 03: Import the NgxScrollPositionRestorationModule to any child module containing child routes. For example:

page-b.module.ts

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';

import { PageBRoutingModule } from './page-b-routing.module';
import { PageBComponent } from './page-b.component';

// Import NgxScrollPositionRestorationModule
import { NgxScrollPositionRestorationModule } from 'ngx-scroll-position-restoration';

@NgModule({
  declarations: [
    PageBComponent
  ],
  imports: [
    CommonModule,
    PageBRoutingModule,
    NgxScrollPositionRestorationModule // Import NgxScrollPositionRestorationModule
  ]
})
export class PageBModule { }

page-b-routing.module.ts

import { NgModule } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';
import { PageBTabAComponent } from './page-b-tab-a/page-b-tab-a.component';
import { PageBTabBComponent } from './page-b-tab-b/page-b-tab-b.component';
import { PageBComponent } from './page-b.component';

const routes: Routes = [
  {
    path: '', component: PageBComponent,
    children: [
      {
        path: 'tab-a',
        component: PageBTabAComponent
      },
      {
        path: 'tab-b',
        component: PageBTabBComponent
      }
    ]
  }
];

@NgModule({
  imports: [RouterModule.forChild(routes)],
  exports: [RouterModule]
})
export class PageBRoutingModule { }

See: projects\demo-app\src\app\page-b\ folder.

Documentation

NgxScrollPositionRestorationModule class

class NgxScrollPositionRestorationModule {
    static forRoot(config?: NgxScrollPositionRestorationConfig);
}

NgxScrollPositionRestorationConfig interface

interface NgxScrollPositionRestorationConfig {
  /**
   * Define how long to poll the document after a route change in order to look for elements that need to be restored to a previous scroll position. Value in milliseconds.
   * 
   * @default
   * 3000 // 3 seconds
   */
  pollDuration?: number;
  /**
   * Define the cadence to pool the document to restore previous scroll positions (maximum until the `pollDuration`). Value in milliseconds.
   * 
   * @default
   * 50
   */
  pollCadence?: number;
  /**
   * Debugging.
   * 
   * @default
   * false
   */
  debug?: boolean;
}

Compatibility

Angular version	Compatible with (tested on)
Angular 6	Yes
Angular 7	Yes
Angular 8	Yes
Angular 9	Yes
Angular 10	Yes
Angular 11	Yes
Angular 12	Yes
Angular 13	Yes

License

MIT