ngx-data-loader

NgxDataLoader

Lightweight Angular 14+ component for easy async data loading.

Description

The NgxDataLoaderComponent lets you load any kind of async data, without having to waste time on common stuff like error handling, cancel/reload strategies and template display logic.

You only need to provide a getDataFn that returns an Observable of the data. You can optionally provide an ng-template for each of the loading states.

Features

• Bring your own template for each loading state (or not)
• Provides reload and cancel methods
• Automatic cancellation of ongoing http requests on cancel/reload/destroy¹
• Configure auto retry and timeout
• Supports server-side rendering through initialData input
• Supports optimistic updates through setData method

Demo

View demo on StackBlitz

Installation

Install the package

npm install ngx-data-loader

Import the module

import { NgxDataLoaderModule } from 'ngx-data-loader';

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

Usage

<!-- app.component.html -->
<ngx-data-loader [getDataFn]="getTodo">
  <!-- showing when data has loaded -->
  <ng-template #dataTemplate let-todo>
    Title: {{ todo.title }} <br />
    Completed: {{ todo.completed ? 'Yes' : 'No' }}
  </ng-template>

  <!-- showing during loading phase -->
  <ng-template #skeletonTemplate> Loading... </ng-template>

  <!-- showing when error occurs -->
  <ng-template #errorTemplate let-error let-retry="reloadFn">
    Oops, something went wrong! Details: {{ error.message }}
    <button (click)="retry()">Retry</button>
  </ng-template>
</ngx-data-loader>

/* app.component.ts */
@Component({
  ...
})
export class AppComponent {
  getTodo = () => this.http.get('https://jsonplaceholder.typicode.com/todos/1');

  constructor(private http: HttpClient) {}
}

Template slots

Name	Description	Local variables
@ContentChild('dataTemplate') dataTemplate?: TemplateRef<unknown>	Template to be displayed when the data is loaded.	$implicit: T: the resolved data. loading: boolean: whether the data is reloading (only available if showStaleData is set to true).
@ContentChild('skeletonTemplate) skeletonTemplate?: TemplateRef<unknown>	Template to be displayed when the data is loading.	(none)
@ContentChild('errorTemplate') errorTemplate?: TemplateRef<unknown>	Template to be displayed when the data failed to load.	$implicit: Error<unknown>: the error object. reloadFn: () => void: can be called to trigger a retry.

Properties

Name	Description
@Input() getDataFn: () => Observable<T>	Function that returns an Observable of the data to be loaded. Called on init and on reload.
@Input() initialData: T	Optional. Data to be rendered on init. When set, getDataFn will not be invoked on init. The loading state will be set to loaded.
@Input() retries: number	Optional. Number of times to retry loading the data. Default: 0
@Input() retryDelay: number	Optional. Delay in milliseconds between retries. Default: 1000
@Input() showStaleData: boolean	Optional. Whether to show stale data while reloading. Default: false
@Input() skeletonDelay: number	Optional. Delay in milliseconds before showing the skeleton. Default: 0
@Input() timeout: number	Optional. Number of milliseconds to wait for getDataFn to emit before throwing an error.

Events

Name	Description
@Output() dataLoaded: EventEmitter<T>	Emitted when the data is loaded.
@Output() loadAttemptStarted: EventEmitter<void>	Emitted when the data loading is started.
@Output() error: EventEmitter<Error>	Emitted when the data failed to load.
@Output() loadAttemptFinished: EventEmitter<void>	Emitted when the data has either loaded or failed to load.
@Output() loadingStateChange: EventEmitter<LoadingState<T>>	Emits entire loading state when any of the above events are emitted.

Methods

Name	Description
reload: () => void	Resets the loading state and calls the getDataFn that you provided.
cancel: () => void	Cancels the pending getDataFn and aborts any related http requests1.
setData: (data: T) => void	Updates the loading state as if the passed data were loaded through getDataFn.
setError: (error: Error) => void	Updates the loading state as if the passed error were thrown by getDataFn.

Interfaces

interface LoadingState<T> {
  loading: boolean;
  loaded: boolean;
  error?: Error;
  data?: T;
}

License

The MIT License (MIT). Please see License File for more information.

Footnotes

1. You must use Angular's HttpClient for http request cancellation to work. ↩ ↩²