ngx-data-loader

NgxDataLoader

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

Description

Most async data loading is done the same way: show a loading indicator while the data is being retrieved, then show the data when it's loaded, or show an error message or a retry button if the data failed to load.

While this seems simple, getting the logic right can be challenging, especially when error handling or data reloading is involved.

The NgxDataLoaderComponent makes it easy. You only need to provide a getDataFn that returns a Promise or Observable of the data, and the data, skeleton and error templates. The component will handle all of the logic for you.

Features

• Bring your own template for each loading state
• Automatic template switching
• Configurable auto retry
• Easy manual retry/reload
• Automatic cancellation of ongoing http requests on reload/destroy

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> | Promise<T>	Function that returns a Promise or Observable of the data to be loaded. Called on init and on reload.
@Input() retries: number	Number of times to retry loading the data. Default: 0
@Input() retryDelay: number	Delay in milliseconds between retries. Default: 1000
@Input() showStaleData: boolean	Whether to show stale data while reloading. Default: false
@Input() skeletonDelay: number	Delay in milliseconds before showing the skeleton. Default: 0
@Input() timeout: number	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	Resets the loading state and calls the getDataFn that you provided.

License

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