ngx-data-loader

NgxDataLoader

Simplify async data loading in Angular with NgxDataLoaderComponent.

Description

The NgxDataLoaderComponent is an Angular component for easy async data loading. It handles error handling, cancel/reload strategies, and template display logic.

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

The component also offers features such as auto retry and timeout configuration, server-side rendering with initialData, and optimistic updates with setData.

Features

• Bring your own template for each loading phase
• 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 [loadFn]="getTodo">
  <ng-template #loading> Loading... </ng-template>

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

  <ng-template #error let-error let-retry="retry">
    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	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. You must use Angular's HttpClient for http request cancellation to work. ↩ ↩²