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/destroy1
- 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
<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<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.