NgxDataLoader
Lightweight, beginner-friendly Angular component that simplifies asynchronous data loading.
Description
NgxDataLoader is an Angular library designed to streamline asynchronous data loading. Its NgxDataLoaderComponent
delivers a hassle-free experience by taking care of observable unsubscription / memory leaks, tracking loading states, managing error handling, and ensuring the correct template displays at the right time.
Key Features
1. NgxDataLoaderComponent: This component accepts a loadFn
function that returns an Observable. It automatically initiates data loading, relieving you from this task.
2. Loading and Error Templates: Optionally, you can add loading and error templates simply by nesting them inside the ngx-data-loader
component. These templates will be displayed automatically based on the current state.
3. Reload Method: NgxDataLoaderComponent exposes a reload
method, enabling you to refresh the data as needed.
4. Automatic Cleanup: When the component gets destroyed, the loading operation is cancelled automatically, preventing potential memory leaks.
5. Dynamic Arguments: With the component's loadFnArgs
input, you can pass arguments to the load function. Any changes to these arguments trigger an automatic reload, making it simple to load data based on dynamic values, like a route's ID parameter.
Benefits
NgxDataLoader has been designed with simplicity and efficiency in mind. By abstracting away complex RxJS operations, it presents a more beginner-friendly approach to managing asynchronous data loading in Angular applications.
In essence, NgxDataLoader helps you focus more on developing your application's core functionality and less on managing state and error handling, resulting in cleaner and more readable code.
Demo
⚡️ View demo on StackBlitz
Installation
Install the package:
npm install ngx-data-loader
Note: this package requires ngx-load-with
as a peer dependency. Please make sure you install that as well. NgxDataLoader requires Angular 16 or higher. For Angular 15 support, use ngx-data-loader@8
Import the module:
import { NgxDataLoaderModule } from 'ngx-data-loader';
@NgModule({
imports: [
NgxDataLoaderModule,
...
],
...
})
export class AppModule {}
Usage
Basic example:
<ngx-data-loader [loadFn]="getTodos">
<ng-template #loading> Loading todos... </ng-template>
<ng-template #error let-error> Failed to load todos. {{error.message}} </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>
@Component({
...
})
export class AppComponent {
getTodos = () => this.http.get('https://jsonplaceholder.typicode.com/todos');
constructor(private http: HttpClient) {}
}
Reloading data:
<button (click)="todosLoader.reload()">Reload Todos</button>
<ngx-data-loader [loadFn]="getTodos" #todosLoader>
...
<ng-template #loaded let-todos>
...
</ng-template>
</ngx-data-loader>
Loading data based on route parameters:
<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>
@Component({
...
})
export class AppComponent {
getTodo = ({id: string}) => this.http.get(`https://jsonplaceholder.typicode.com/todos/${id}`);
constructor(private http: HttpClient, public route: ActivatedRoute) {}
}
Loading data based on search input:
⚡️ Open on StackBlitz
⚡️ View advanced demo on StackBlitz
<h1>Search</h1>
<input ngModel #searchbox placeholder="Search" />
<ngx-data-loader *ngIf="searchbox.value as keywords" [loadFn]="searchProducts" [loadFnArgs]="keywords" [debounceTime]="300">
<ng-template #loading> Searching... </ng-template>
<ng-template #error> Error </ng-template>
<ng-template #loaded let-results>
<h2>{{results.total}} search results for "{{ keywords }}"</h2>
<div *ngFor="let product of results.products">
<h3>{{product.title}}</h3>
<p>{{product.description}}</p>
</div>
</ng-template>
</ngx-data-loader>
@Component({
...
})
export class AppComponent {
searchProducts = (keywords: string) =>
this.http.get('https://dummyjson.com/products/search', {
params: { q: keywords },
});
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()
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 |
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;
}
FAQ
How to get type safety for the data loaded by NgxDataLoaderComponent
?
Angular currently does not support type inference for template variables. This means that the type of the data loaded by NgxDataLoader
cannot be inferred from the template. A good workaround is to use a presentational component inside the #loaded
template that takes the loaded data as a typed input.
For example:
<ngx-data-loader [loadFn]="getTodos">
...
<ng-template #loaded let-todos>
<app-todo-list [todos]="todos"></app-todo-list>
</ng-template>
</ngx-data-loader>
@Component({
...
})
export class TodoListComponent {
@Input() todos: Todo[];
}
By doing this, you can ensure type safety in your presentational component's template while still taking advantage of the convenience provided by ngx-data-loader.
If the lack of intellisense in your template is a dealbreaker for you, there's an alternative! You can directly use the ngx-load-with
directive, which was authored by the same author and does support template type inference. While its API is slightly different, it's similar enough to ngx-data-loader that you'll be comfortable using it.
Contributing
Please read CONTRIBUTING.md.
License
The MIT License (MIT). Please see License File for more information.
Contact Information
For any issues or questions regarding the ngx-data-loader
, please use the GitHub issues page.