The NgFor 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.

Local Variables

NgFor provides several exported values that can be aliased to local variables:

  • index will be set to the current loop iteration for each template context.
  • first will be set to a boolean value indicating whether the item is the first one in the iteration.
  • last will be set to a boolean value indicating whether the item is the last one in the iteration.
  • even will be set to a boolean value indicating whether this item has an even index.
  • odd will be set to a boolean value indicating whether this item has an odd index.

Change Propagation

When the contents of the iterator changes, NgFor 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.

Examples

<div *ngFor="let hero of heroes">{{hero.name}}</div>
<hero-detail *ngFor="let hero of heroes" [hero]="hero"></hero-detail>
<div *ngFor="let hero of heroes; let i=index; let odd=odd; trackBy: trackById"
     [class.odd]="odd">
  ({{i}}) {{hero.name}}
</div>

<div template="ngFor let hero of heroes; let i=index; let odd=odd; trackBy: trackById"
     [class.odd]="odd">
  ({{i}}) {{hero.name}}
</div>

<template ngFor let-hero [ngForOf]="heroes" let-i="index" let-odd="odd"
          [ngForTrackBy]="trackById">
  <div [class.odd]="odd">({{i}}) {{hero.name}}</div>
</template>

For details, see the ngFor discussion in the Template Syntax page.

Implements
Annotations
  • @Directive(selector: '[ngFor][ngForOf]', inputs: const ['ngForTrackBy', 'ngForOf', 'ngForTemplate'], visibility: Visibility.none)

Constructors

NgFor(ViewContainerRef _viewContainer, TemplateRef _templateRef)

Properties

ngForOf value
write-only
ngForTemplate TemplateRef value
write-only
ngForTrackBy TrackByFn value
write-only
hashCode → int
The hash code for this object. [...]
read-only, inherited
runtimeType → Type
A representation of the runtime type of the object.
read-only, inherited

Methods

ngDoCheck() → void
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
toString() → String
Returns a string representation of this object.
inherited

Operators

operator ==(other) → bool
The equality operator. [...]
inherited