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 stated
- Provides
reload
and cancel
methods - Automatic cancellation of ongoing http requests on cancel/reload/destroy1
- 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
<ngx-data-loader [getDataFn]="getTodo">
<ng-template #dataTemplate let-todo>
Title: {{ todo.title }} <br />
Completed: {{ todo.completed ? 'Yes' : 'No' }}
</ng-template>
<ng-template #skeletonTemplate> Loading... </ng-template>
<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>
@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 | 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 | 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> | Emits when the data is loaded. |
@Output()
loadAttemptStarted: EventEmitter<void> | Emits when the data loading is started. |
@Output()
error: 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 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.