NgForOf
The NgForOf
directive instantiates a template once per item from an iterable. The context
for each instantiated template inherits from the outer context with the given loop variable
set to the current item from the iterable.
NgModule
Selectors
Properties
Property | Description |
---|---|
@Input()
|
Write-only. |
@Input()
|
|
@Input()
|
Write-only. |
Description
Local Variables
NgForOf
provides several exported values that can be aliased to local variables:
$implicit: T
: The value of the individual items in the iterable (ngForOf
).ngForOf: NgIterable<T>
: The value of the iterable expression. Useful when the expression is more complex then a property access, for example when using the async pipe (userStreams | async
).index: number
: The index of the current item in the iterable.first: boolean
: True when the item is the first item in the iterable.last: boolean
: True when the item is the last item in the iterable.even: boolean
: True when the item has an even index in the iterable.odd: boolean
: True when the item has an odd index in the iterable.
<li *ngFor="let user of userObservable | async as users; index as i; first as isFirst">
{{i}}/{{users.length}}. {{user}} <span *ngIf="isFirst">default</span>
</li>
Change Propagation
When the contents of the iterator changes, NgForOf
makes the corresponding changes to the DOM:
- When an item is added, a new instance of the template is added to the DOM.
- When an item is removed, its template instance is removed from the DOM.
- When items are reordered, their respective templates are reordered in the DOM.
- Otherwise, the DOM element for that item will remain the same.
Angular uses object identity to track insertions and deletions within the iterator and reproduce
those changes in the DOM. This has important implications for animations and any stateful
controls (such as <input>
elements which accept user input) that are present. Inserted rows can
be animated in, deleted rows can be animated out, and unchanged rows retain any unsaved state
such as user input.
It is possible for the identities of elements in the iterator to change while the data does not. This can happen, for example, if the iterator produced from an RPC to the server, and that RPC is re-run. Even if the data hasn't changed, the second response will produce objects with different identities, and Angular will tear down the entire DOM and rebuild it (as if all old elements were deleted and all new elements inserted). This is an expensive operation and should be avoided if possible.
To customize the default tracking algorithm, NgForOf
supports trackBy
option.
trackBy
takes a function which has two arguments: index
and item
.
If trackBy
is given, Angular tracks changes by the return value of the function.
Syntax
With <ng-template>
element:
<ng-template ngFor let-item [ngForOf]="items" let-i="index" [ngForTrackBy]="trackByFn">
<li>...</li>
</ng-template>
Example
See a live demo for a more detailed example.
Methods
ParametersThere are no parameters. Returns
|