function

`{{#each EXPRESSION}}FN{{else}}INVERSE{{/each}}`

Render FN for each item in EXPRESSION's return value. If EXPRESSION is falsey or an empty list, render INVERSE.

{{#each todos}}
  <li>{{name}}</li>
{{else}}
  <li>No todos, rest easy!</li>
{{/each}}

Parameters

EXPRESSION {KeyLookup Expression|Call Expression}:
An expression that typically returns a list like data structure.

If the value of the EXPRESSION is a can-define/list/list or can-list, the resulting HTML is updated when the list changes. When a change in the list happens, only the minimum amount of DOM element changes occur. The list itself can also change, and a diff will be performed, which also will perform a minimal set of updates. The special %key key is available within FN.

If the value of the key is an object, FN will be called for each property on the object. The special %key key is available within FN.
FN {sectionRenderer(context, helpers)}:
A subsection that will be rendered with each item in EXPRESSION or property value in EXPRESSION.
INVERSE {sectionRenderer(context, helpers)}:
An optional subsection that will be rendered if EXPRESSION is falsey or an empty list or object.

`{{#each EXPRESSION as KEY}}FN{{else}}INVERSE{{/each}}`

Like a normal {{#each EXPRESSION}}, but adds each item in EXPRESSION as KEY in FN's can-view-scope.

{{#each todos as todo}}
    <li>{{todo.name}}</li>
{{/each}}

Parameters

EXPRESSION {KeyLookup Expression|Call Expression}:
An expression that returns a list or object like data structure.
key {key}:
The name that:
- each item in EXPRESSION's list, or
- each property value in EXPRESSION's object should take on in FN.
FN {sectionRenderer(context, helpers)}:
A subsection that will be rendered with each item in EXPRESSION or property value in EXPRESSION.
INVERSE {sectionRenderer(context, helpers)}:
An optional subsection that will be rendered if EXPRESSION is falsey or an empty list or object.

Use

Use the each helper to iterate over a array of items and render the block between the helper and the slash. For example,

The template:

<ul>
  {{#each friends}}
    <li>{{name}}</li>
  {{/each}}
</ul>

Rendered with:

{friends: [{name: "Austin"},{name: "Justin"}]}

Renders:

<ul>
  <li>Austin</li>
  <li>Justin</li>
</ul>

Object iteration

When iterating over can-map it will only iterate over the map's keys and none of the hidden properties of a Map. For example,

The template:

<ul>
  {{#each person}}
    <li>{{.}}</li>
  {{/each}}
</ul>

Rendered with:

{person: {name: 'Josh', age: 27}}

Renders:

<ul>
  <li>Josh</li>
  <li>27</li>
</ul>

Understanding when to use #each with lists

{{#each key}} iteration will do basic diffing and aim to only update the DOM where the change occurred. Whereas {{#expression}} default iteration will re-render the entire section for any change in the list. {{#expression}} iteration is the preferred method to use when a list is replaced or changing significantly. When doing single list item changes frequently, {{#each expression}} iteration is the faster choice.

For example, assuming "list" is a can-define/list/list instance:

{{#each list}} and {{#list}} both iterate through an instance of can-define/list/list, however we setup the bindings differently.

{{#each list}} will setup bindings on every individual item being iterated through, while {{#list}} will not. This makes a difference in two scenarios:

You have a large list, with minimal updates planned after initial render. In this case, {{#list}} might be more advantageous as there will be a faster initial render. However, if any part of the list changes, the entire {{#list}} area will be re-processed.
You have a large list, with many updates planned after initial render. A grid with many columns of editable fields, for instance. In this case, you many want to use {{#each list}}, even though it will be slower on initial render(we're setting up more bindings), you'll have faster updates as there are now many sections.