ngx-connection-service

Internet Connection Monitoring Service

Detects whether browser has an active internet connection or not in Angular application.

This library is a fork of https://github.com/ultrasonicsoft/ng-connection-service by Balram Chavan.

Install

npm i ngx-connection-service --save

Server-Side Rendering (SSR)

No extra dependencies are required for Angular Universal / SSR. On the server, the service uses a Window stub with navigator.onLine = true and logs a console warning. Online/offline DOM events are only active in the browser after hydration.

Angular Version Compatibility

Please use following table to determine suitable library version for your Angular project.

ngx-connection-service version	Angular version
7.0.x	7.2.16
8.0.x	8.2.14
9.0.x	9.1.13
10.0.x	10.2.5
11.0.x	11.2.14
12.0.x	12.2.17
13.0.x	13.4.0
14.0.x	14.3.0
15.0.x	15.2.9
16.0.x	16.1.8
17.0.x	17.1.0
18.0.x	18.1.2
19.0.x	19.2.25
20.0.x	20.3.27
21.0.x	21.2.20
22.0.x	22.1.2

Usage

• Register provideConnectionService() in your application's providers (standalone / ApplicationConfig).

import {ApplicationConfig} from '@angular/core';
import {provideConnectionService} from 'ngx-connection-service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideConnectionService(),
  ],
};

import {bootstrapApplication} from '@angular/platform-browser';
import {AppComponent} from './app/app.component';
import {appConfig} from './app/app.config';

bootstrapApplication(AppComponent, appConfig)
  .catch(err => console.error(err));

Legacy NgModule setup: ConnectionServiceModule is still available and works, but is deprecated. Prefer provideConnectionService() above.

import {NgModule} from '@angular/core';
import {ConnectionServiceModule} from 'ngx-connection-service';

@NgModule({
  imports: [ConnectionServiceModule],
})
export class AppModule {
}

• Inject ConnectionService using inject() (or the constructor) in your component.
• Read the reactive state Signal, or subscribe to monitor() for push notifications whenever the connection status changes. Both APIs are kept in sync (dual API).

import { Component, inject } from '@angular/core';
import { ConnectionService } from 'ngx-connection-service';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  private readonly connectionService = inject(ConnectionService);

  // Signal API (recommended for modern, signal-based Angular apps)
  readonly currentState = this.connectionService.state;

  constructor() {
    // Observable API (still fully supported)
    this.connectionService.monitor().subscribe(currentState => {
      console.log(currentState);
    });
  }
}

In the template you can then read the Signal directly:

@if (currentState().hasNetworkConnection && currentState().hasInternetAccess) {
  <span>ONLINE</span>
} @else {
  <span>OFFLINE</span>
}

Configuration

You can configure the service using ConnectionServiceOptions configuration variable. Following options are available;

/**
 * Instance of this interface could be used to configure "ConnectionService".
 */
export interface ConnectionServiceOptions {
  /**
   * Controls the Internet connectivity heartbeat system. Default value is 'true'.
   */
  enableHeartbeat?: boolean;
  /**
   * Url used for checking Internet connectivity, heartbeat system periodically makes "HEAD" requests to this URL to determine Internet
   * connection status. Default value is "//api.ipify.org/".
   */
  heartbeatUrl?: string;
  /**
   * Callback function to used for executing heartbeat requests. Defaults to HttpClient.request(...) function.
   */
  heartbeatExecutor?: (options?: ConnectionServiceOptions) => Observable<any>;
  /**
   * Interval used to check Internet connectivity specified in milliseconds. Default value is "30000".
   */
  heartbeatInterval?: number;
  /**
   * Interval used to retry Internet connectivity checks when an error is detected (when no Internet connection). Default value is "1000".
   */
  heartbeatRetryInterval?: number;
  /**
   * HTTP method used for requesting heartbeat Url. Default is 'get'.
   */
  requestMethod?: 'get' | 'post' | 'head' | 'options';

}

You should provide ConnectionServiceOptions via provideConnectionService(options) as follows;

import {ApplicationConfig} from '@angular/core';
import {ConnectionServiceOptions, provideConnectionService} from 'ngx-connection-service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideConnectionService({
      enableHeartbeat: false,
      heartbeatUrl: '/assets/ping.json',
      requestMethod: 'get',
      heartbeatInterval: 3000
    } satisfies ConnectionServiceOptions),
  ],
};

Custom HeartBeat handling function

You could use a callback function for handling heartBeat requests by defining heartbeatExecutor property in ConnectionServiceOptions;

import { Component, inject } from '@angular/core';
import { ConnectionService } from 'ngx-connection-service';
import {Observable} from 'rxjs';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  private readonly connectionService = inject(ConnectionService);

  readonly currentState = this.connectionService.state;

  constructor() {
    this.connectionService.updateOptions({
      heartbeatExecutor: options => new Observable<any>(subscriber => {
        if (Math.random() > .5) {
          subscriber.next();
          subscriber.complete();
        } else {
          throw new Error('Connection error');
        }
      })
    });
  }
}

Testing your own code that uses ConnectionService

ConnectionService uses RxJS timer()/debounceTime() internally (heartbeat polling, retry delay, and state debouncing). If you write unit tests that need to wait for these internal delays, you don't need zone.js's fakeAsync/tick. Instead, provide ConnectionServiceSchedulerToken with an RxJS TestScheduler (from rxjs/testing) and advance its virtual clock synchronously:

import {TestBed} from '@angular/core/testing';
import {TestScheduler} from 'rxjs/testing';
import {ConnectionService, ConnectionServiceSchedulerToken} from 'ngx-connection-service';

const scheduler = new TestScheduler(() => {});

TestBed.configureTestingModule({
  providers: [
    ConnectionService,
    {provide: ConnectionServiceSchedulerToken, useValue: scheduler},
    // ...your other providers (e.g. provideHttpClient, provideHttpClientTesting)
  ],
});

const service = TestBed.inject(ConnectionService);

// Advance virtual time by 300ms synchronously instead of really waiting:
scheduler.maxFrames = scheduler.frame + 300;
scheduler.flush();

This keeps tests instantaneous and fully zoneless. ConnectionServiceSchedulerToken is optional — when not provided, the service defaults to RxJS's regular asyncScheduler (real timers), which is what you want in production.

Changes

• Zoneless: the demo application and library tests no longer depend on zone.js. The app uses provideZonelessChangeDetection(); tests use RxJS TestScheduler virtual time instead of fakeAsync/tick.
• Standalone-first API: provideConnectionService() replaces ConnectionServiceModule for ApplicationConfig / bootstrapApplication setups. ConnectionServiceModule is kept for backward compatibility but is deprecated.
• ConnectionService now exposes a reactive state Signal in addition to the existing monitor() Observable API (dual API, non-breaking).
• Demo application converted to standalone components using the new @if control-flow syntax and inject().
• This version use https://api.ipify.org/ to determine Internet connection status
• Removed dependency to "ssr-window" package

Security / Dependency Status

Upgrade Matrix (current tree)

Package group	Previous range	Current range	Decision
Angular runtime (@angular/*)	^21.2.20	^22.1.2	Upgraded to latest 22.x runtime patches.
Angular build chain (@angular-devkit/build-angular, @angular/cli, @angular/compiler-cli, @angular/language-service, ng-packagr)	21.x	22.x	Upgraded to latest Angular 22 tooling patches.
Lint stack (angular-eslint, eslint, @eslint/js, @typescript-eslint/*, typescript-eslint)	Angular-eslint 21.4.0	Angular-eslint 22.1.0 + ESLint 10.x companions	Upgraded to latest Angular 22-compatible lint toolchain.
Type defs (@types/node, @types/jasmine)	previous majors	Latest Node/Jasmine types compatible with current toolchain	Retained at latest compatible versions.
Test UI reporter (karma-jasmine-html-reporter, jasmine-core)	2.1.0 / 5.1.x	2.2.0 / 6.3.x	Upgraded to latest compatible versions.
TypeScript toolchain (typescript)	~5.9.3	~6.0.3	Upgraded to satisfy Angular 22 peer requirements.
Overrides (less, uuid, webpack-dev-server)	Fixed versions in overrides	removed	Removed; now resolved by upstream transitive graph.
E2E stack (protractor, jasmine-spec-reporter, ts-node)	present	removed	Fully removed from current tree.

Exceptions (latest-version policy with Angular 22 compatibility)

• zone.js has been removed entirely. The application and library now run zoneless via provideZonelessChangeDetection(); zone.js is only an optional peer of @angular/core and is not installed.
• Angular runtime/build packages are intentionally pinned to latest 22.x (not 23+) to maintain declared Angular 22 compatibility for this release line.
• @angular/cli 22 requires Node.js ^22.22.3 || ^24.15.0 || >=26.0.0; run with a matching Node patch version before executing Angular CLI commands.
• If a dependency cannot move to its global latest version without breaking Angular 22 peer constraints, it is pinned to the highest Angular 22-compatible release.

License

MIT License Argela Inc. & Balram Chavan (orginal work)