ngx-data-loader

NgxDataLoader

Lightweight Angular component that loads async data, handles errors and switches templates based on loading state.

Description

The NgxDataLoaderComponent lets you easily load any kind of async data, without having to worry about error handling, reloading and UI logic.

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

Features

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

Demo

View demo on StackBlitz

Getting started

Install the package

npm install ngx-data-loader

Import the module

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

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

Use the component

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

  <!-- showing during initial 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<any>	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<any>	Template to be displayed when the data is loading.	(none)
@ContentChild('errorTemplate') errorTemplate?: TemplateRef<any>	Template to be displayed when the data failed to load.	$implicit: Error<any>: 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. ↩ ↩²