Skip to main content

​
Overview

Iteration allows you to render lists of data in your Lightning Web Components. LWC provides two directives for rendering arrays: for:each for simple lists and iterator for advanced scenarios where you need access to index or first/last information.

​
for:each Directive

The for:each directive is the most common way to render lists. It’s simple, performant, and ideal for most use cases.

​
Implementation

import { LightningElement } from 'lwc';

export default class HelloForEach extends LightningElement {
    contacts = [
        {
            Id: '003171931112854375',
            Name: 'Amy Taylor',
            Title: 'VP of Engineering'
        },
        {
            Id: '003192301009134555',
            Name: 'Michael Jones',
            Title: 'VP of Sales'
        },
        {
            Id: '003848991274589432',
            Name: 'Jennifer Wu',
            Title: 'CEO'
        }
    ];
}

​
Key Concepts for for:each

​
The for:each Attribute

<template for:each={contacts} for:item="contact">
  • for:each={contacts} - The array to iterate over
  • for:item="contact" - The variable name for each item (in quotes)
  • Inside the template, access the current item using {contact}

​
The key Attribute

<li key={contact.Id}>{contact.Name}, {contact.Title}</li>
The key attribute is required for all elements inside a for:each loop. It must be a unique identifier for each item.
  • Helps LWC efficiently update the DOM when the list changes
  • Must be unique within the list
  • Should be stable (same item always has the same key)
Use a unique ID from your data (like Id, recordId, or uuid) rather than array indexes for the key. This ensures proper rendering when items are added, removed, or reordered.

​
What You’ll See

The component renders a bulleted list:
  • Amy Taylor, VP of Engineering
  • Michael Jones, VP of Sales
  • Jennifer Wu, CEO

​
iterator Directive

The iterator directive provides access to additional metadata about each iteration, including whether an item is first or last in the list.

​
Implementation

import { LightningElement } from 'lwc';

export default class HelloIterator extends LightningElement {
    contacts = [
        {
            Id: '003171931112854375',
            Name: 'Amy Taylor',
            Title: 'VP of Engineering'
        },
        {
            Id: '003192301009134555',
            Name: 'Michael Jones',
            Title: 'VP of Sales'
        },
        {
            Id: '003848991274589432',
            Name: 'Jennifer Wu',
            Title: 'CEO'
        }
    ];
}

​
Key Concepts for iterator

​
The iterator Attribute

<template iterator:it={contacts}>
  • iterator:it={contacts} - Creates an iterator named it for the contacts array
  • The iterator name (it) can be any valid identifier

​
Iterator Properties

The iterator object provides several properties:
  • it.value - The current item in the array
  • it.index - The zero-based index of the current item
  • it.first - true if this is the first item
  • it.last - true if this is the last item
<li key={it.value.Id}>
    <div lwc:if={it.first} class="list-first"></div>
    {it.value.Name}, {it.value.Title}
    <div lwc:if={it.last} class="list-last"></div>
</li>
Use iterator when you need to:
  • Apply special styling or behavior to the first or last item
  • Display item numbers (using it.index)
  • Add separators between items (except before first or after last)

​
What You’ll See

The component renders a list with special markers:
  • (first marker) Amy Taylor, VP of Engineering
  • Michael Jones, VP of Sales
  • Jennifer Wu, CEO (last marker)

​
When to Use Each Directive

​
Use for:each when:

  • You have a simple list to render
  • You don’t need index or first/last information
  • You want cleaner, more readable templates

​
Use iterator when:

  • You need to know if an item is first or last
  • You need the item’s index
  • You want to apply special styling to boundary items
  • You need to add separators between items

​
Common Patterns

​
Nested Arrays

<template for:each={categories} for:item="category">
    <div key={category.id}>
        <h3>{category.name}</h3>
        <ul>
            <template for:each={category.products} for:item="product">
                <li key={product.id}>{product.name}</li>
            </template>
        </ul>
    </div>
</template>

​
Conditional Items

<template for:each={items} for:item="item">
    <div key={item.id}>
        <template lwc:if={item.isVisible}>
            {item.name}
        </template>
    </div>
</template>

​
Item Separators

<template iterator:it={items}>
    <span key={it.value.id}>
        {it.value.name}
        <span lwc:if={it.last}> | </span>
    </span>
</template>

​
Best Practices

Always provide unique keys: Use stable, unique identifiers from your data. Avoid using array indexes as keys unless the list never changes.
Iterate over arrays only: The for:each and iterator directives work only with arrays, not objects. To iterate over object properties, convert them to an array first.
Keep templates flat: Avoid deeply nested iterations when possible. Consider breaking complex lists into separate child components.

​
Converting Objects to Arrays

If you need to iterate over object properties: 
get itemsArray() {
    return Object.entries(this.itemsObject).map(([key, value]) => ({
        id: key,
        ...value
    }));
}

<template for:each={itemsArray} for:item="item">
    <div key={item.id}>{item.name}</div>
</template>

​
Performance Considerations

Use for:each by default: It’s simpler and has slightly better performance than iterator for basic lists.
Large lists: For very large lists (1000+ items), consider:
  • Virtual scrolling or pagination
  • Lazy loading as users scroll
  • Filtering to reduce visible items

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us