Welcome to `NgxLoadWith`, a powerful tool for Observable-based data loading in Angular.
npm install ngx-load-withWelcome to NgxLoadWith, a powerful tool for Observable-based data loading in Angular.
``angular`
You have {{ count }} unread messages
With NgxLoadWithDirective, you can easily display data from an Observable in your template. You won’t have to worry about performance, errors, or managing the loading state. Plus, it lets you handle reloading and more advanced tasks, all with minimal RxJS knowledge.
Key Features:
- 💡 Declarative UI State Management: Automates transitions between loading, success, and error states, eliminating the need for if-statements.
- 🚀 Performance: Optimized for efficiency, aligns with Angular's OnPush change detection.
- 🛡️ Memory Safety: Automatically unsubscribes from Observables to prevent memory leaks.
- ⚖️ Lightweight and Independent: Zero dependencies, easily integrates into any project.
- ⚡️ Dynamic Data Loading: Supports loading data based on dynamic parameters.
- 🎮 Control Over Data Loading: Offers methods for reloading and canceling requests.
- Demo
- Installation
- Usage
- Basic usage
- Showing loading and error templates
- Loading based on changes to other data
- Reloading
- Showing previously loaded data while reloading
- Note on Microsyntax
- API
- Inputs
- Outputs
- Methods
- License
- Contributing
- Credits
Check out these live examples of NgxLoadWith in action:
- ⚡️ Basic Usage Example: Easily load data and show loading and error templates.
- ⚡️ Advanced Usage Example: Load data based to changes in a searchbar.
To install NgxLoadWith, run the following command:
`bash`
npm install ngx-load-with
> Note: you need Angular version 16 or higher. For Angular 15, use ngx-load-with@1.
To use NgxLoadWith, import NgxLoadWithDirective in your Angular component:
`typescript
import { NgxLoadWithDirective } from "ngx-load-with";
@Component({
selector: "app-my-component",
templateUrl: "./my-component.component.html",
standalone: true,
imports: [NgxLoadWithDirective],
})
export class MyComponent {}
`
> Note: in projects using NgModules, NgxLoadWithModule can be imported in your Angular module.
Load data from an Observable and display it in your template:
⚡️ Live Example
`angular`
@for (todo of todos; track todo.id) {
}
`typescript`
@Component({...})
export class MyComponent {
todos$ = inject(HttpClient).get
}
Display a loading message while data is being loaded, and an error message if an error occurs:
⚡️ Live Example
`angular`
>
@for (todo of todos; track todo.id) {
}
NgxLoadWith can respond to dynamic data changes using a function in place of a plain Observable. This function is invoked when the input arguments change.
Example 1: Fetching data using route parameters:
`angular`
{{ todo.title }}
`typescript
@Component({...})
export class MyComponent {
routeParams$ = inject(ActivatedRoute).params;
getTodo = ({id}) => this.http.get
private http = inject(HttpClient);
}
`
Example 2: Searching data based on user input:
`angular`
@for (todo of todos; track todo.id) {
}
`typescript
@Component({...})
export class MyComponent {
findTodos = (keywords: string) => this.http.get
private http = inject(HttpClient);
}
`
In these examples, getTodo and findTodos are functions that return Observables based on dynamic parameters. When these parameters change, NgxLoadWith automatically invokes the respective function with the updated parameters, effectively reloading the data.
Reload data when a button is clicked:
⚡️ Live Example
`angular
@for (todo of todos; track todo.id) {
}
`
> Important: If you plan to use the NgxLoadWithDirective.load method in your template, please note that you cannot use the *ngxLoadWith microsyntax. See note on microsyntax for more details.
Reload data when a button is clicked, but display stale data while the new data is being loaded:
⚡️ Live Example
`angular
[ngxLoadWith]="todos$"
[ngxLoadWithStaleData]="true"
let-todos
let-loading="loading"
>
@if (loading) {
Reloading...
}
> Important: If you plan to use the
method in your template, please note that you cannot use the *ngxLoadWith microsyntax. See note on microsyntax for more details.Note on Microsyntax
When using the
NgxLoadWithDirective, you have two options for syntax:1. Microsyntax: This shorter, more compact syntax is easy to read and sufficient for many common use cases. For example:
`angular
...
`2. Normal syntax: The longer form syntax is necessary when you need to create a directive reference in your template or listen to output events emitted by the directive. For example:
angular
[ngxLoadWith]="getTodo"
[ngxLoadWithArgs]="id"
let-todo
>
...
` In this example,
creates a reference to the NgxLoadWithDirective instance, allowing you to call the load() method in your template:
`angular
` Additionally, using the normal syntax allows you to listen to output events:
angular
[ngxLoadWith]="getTodos"
(loadSuccess)="onSuccess($event)"
(loadError)="onError($event)"
let-todos
>
...
`API
$3
-
: A function returning an Observable of the data to be loaded, or a plain Observable.
- args: unknown: An argument to be passed to the ngxLoadWith function (if it's a function). Changes to this argument will trigger a reload.
- loadingTemplate: TemplateRef: An optional template to be displayed while the data is being loaded.
- errorTemplate: TemplateRef: An optional template to be displayed when an error occurs while loading the data.
- debounceTime: number: The amount of time in milliseconds to debounce the load trigger.
- staleData: boolean: A boolean indicating whether to show previously loaded data while reloading.$3
-
loadStart: EventEmitter: Emits when the data loading process starts.
- loadSuccess: EventEmitter: Emits when the data loading process is successful.
- loadError: EventEmitter: Emits when an error occurs while loading the data.
- loadFinish: EventEmitter: Emits when the data loading process finishes, regardless of success or failure.
- loadingStateChange: EventEmitter: Emits when the loading state changes.> Important: If you plan to listen to the above output events, please note that you cannot use the
*ngxLoadWith microsyntax. See note on microsyntax for more details on using the normal syntax.$3
-
load(): Triggers a reload of the data. Previous load requests are cancelled.
- cancel(): Cancels any pending load requests.
- setData(data: T): Updates the loading state as if the passed data were loaded through the ngxLoadWith function.
- setError(error: Error): Updates the loading state as if the passed error were thrown by the ngxLoadWith function.> Important: If you plan to use the above methods in your template, please note that you cannot use the
*ngxLoadWith microsyntax. See note on microsyntax for more details on using the normal syntax.$3
`typescript
interface LoadingState {
loading: boolean;
loaded: boolean;
error?: Error | null;
data?: T;
}interface LoadedTemplateContext {
$implicit: T;
ngxLoadWith: T;
loading: boolean;
}
interface ErrorTemplateContext {
$implicit: Error;
retry: () => void;
}
`License
Contributions are welcome! See the CONTRIBUTING file for details.
This project is developed and managed by Rens Jaspers. It draws significant inspiration from ngx-observe and react-async.