ngx-data-loader

NgxDataLoader

Simplify async data loading in Angular with NgxDataLoaderComponent.

Description

NgxDataLoaderComponent simplifies asynchronous data loading in Angular by abstracting away tedious tasks such as error handling, cancel/reload strategies, and template display logic. This helps you focus on the core functionality of your application.

A key feature of NgxDataLoaderComponent is its ability to handle dynamic arguments through the use of loadFnArgs. This feature enables you to pass in dynamic arguments to loadFn, and each time the value changes, loadFn is triggered with the new arguments. This makes it easy to load data based on route parameters or the value of an input field.

To use the component, provide a loadFn that returns an Observable of the data, and optional templates for each loading phase.

Features

• Declarative syntax that handles display and loading logic behind the scenes
• Automatic reload on input changes
• Provides reload and cancel methods
• Automatic cancellation of ongoing http requests on cancel/reload/destroy¹
• Configurable retry and timeout

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

Basic example:

<!-- app.component.html -->
<ngx-data-loader [loadFn]="getTodo">
  <ng-template #loading> Loading todos... </ng-template>

  <ng-template #error> Failed to load todos. </ng-template>

  <ng-template #loaded let-todos>
    <div *ngFor="let todo of todos">
      Title: {{ todo.title }} <br />
      Completed: {{ todo.completed ? 'Yes' : 'No' }}
    </div>
  </ng-template>
</ngx-data-loader>

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

  constructor(private http: HttpClient) {}
}

Loading data based on route parameters:

<!-- app.component.html -->
<ngx-data-loader [loadFn]="getTodo" [loadFnArgs]="route.params | async">
  <ng-template #loading> Loading todo... </ng-template>

  <ng-template #error> Failed to load todo. </ng-template>

  <ng-template #loaded let-todo>
    Title: {{ todo.title }} <br />
    Completed: {{ todo.completed ? 'Yes' : 'No' }}
  </ng-template>
</ngx-data-loader>

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

  constructor(private http: HttpClient, public route: ActivatedRoute) {}
}

Template slots

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

Properties

Name	Description
@Input() loadFn!: () => Observable<T>	Function that returns an Observable of the data to be loaded. Called on init and on reload.
@Input() loadFnArgs?: any	Arguments to pass to loadFn. Changes to this property will trigger a reload.
@Input() initialData?: T	Data to be rendered on init. When set, loadFn will not be invoked on init. The loading state will be set to loaded.
@Input() debounceTime: number	Number of milliseconds to debounce reloads.
@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 keep displaying previously loaded data while reloading. Default: false
@Input() loadingTemplateDelay: number	Delay in milliseconds before showing the loading template. Default: 0
@Input() timeout?: number	Number of milliseconds to wait for loadFn to emit before throwing an error.

Events

Name	Description
@Output() dataLoaded: EventEmitter<T>	Emits when the data is loaded.
@Output() loadAttemptStarted: EventEmitter<void>	Emits when the data loading is started.
@Output() loadAttemptFailed: EventEmitter<Error>	Emits when the data fails to load.
@Output() loadAttemptFinished: EventEmitter<void>	Emits 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 loadFn that you provided.
cancel: () => void	Cancels the pending loadFn and aborts any related http requests1.
setData: (data: T) => void	Updates the loading state as if the passed data were loaded through loadFn.
setError: (error: Error) => void	Updates the loading state as if the passed error were thrown by loadFn.

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. Automatic cancellation of http requests requires support from the underlying http library. It works out of the box with Angular's HttpClient, but may require additional configuration if using a different library ↩ ↩²