Mastering List Iteration in Salesforce LWC: for:each Directive Guide

In plain words: List Iteration in Lightning Web Components (LWC) allows you to render collections of data dynamically in your HTML templates using the for:each directive. By looping through arrays of strings, numbers, or sObjects, you can build flexible, reusable UI lists and tables that update automatically when component state changes.

Building dynamic user interfaces in Salesforce often requires rendering lists of records—such as account search results, related contacts, or task items. Lightning Web Components simplifies this process using template directives like for:each and iterator:it. Mastering list iteration is an essential step for every LWC developer.

1. How List Iteration Works in LWC

Rendering dynamic collections in LWC relies on two core template attributes:

• for:each={collection}: Specifies the JavaScript array property to iterate over.
• for:item="itemName": Assigns the current element in the loop to a variable name for use inside the template block.
• key={uniqueId}: A mandatory unique identifier assigned to the immediate sibling inside the loop to help LWC optimize virtual DOM re-rendering.

360 LWC Iteration Architecture Card:

• Directive Syntax: <template for:each={items} for:item="item">
• Required Attribute: key={item.Id} on the immediate child tag.
• Alternative Directive: iterator:it={items} (provides it.first and it.last helper properties).

2. Step-by-Step Implementation

Step 1: JavaScript Controller (iterationExample.js)
Define the array property in your component class.

import { LightningElement } from 'lwc';

export default class IterationExample extends LightningElement {
    items = [
        { id: '1', name: 'Alpha Project' },
        { id: '2', name: 'Beta Deployment' },
        { id: '3', name: 'Gamma Migration' },
        { id: '4', name: 'Delta Upgrade' }
    ];
}

Step 2: HTML Template (iterationExample.html)
Iterate over the array using the for:each directive.

<template>
    <lightning-card title="Project Iteration List" icon-name="standard:record">
        <div class="slds-p-around_medium">
            <ul class="slds-list_dotted">
                <template for:each={items} for:item="item">
                    <li key={item.id} class="slds-m-bottom_x-small">
                        <strong>{item.name}</strong>
                    </li>
                </template>
            </ul>
        </div>
    </lightning-card>
</template>

3. Common Traps & Best Practices

Virtual DOM Trap: Omitting the Key Attribute or Using Index Keys
Failing to include a key attribute on the iterated element will trigger console errors and break LWC rendering efficiency. Furthermore, avoid using array index numbers (e.g., key={index}) if your list items can be reordered, added, or deleted, as this causes UI state bugs. Always use a unique primitive record ID.

Core Rule: Always provide a unique primitive key attribute on the immediate iterated element, use semantic SLDS styling classes, and prefer record IDs over array indices.

• Null and Empty Check: Always verify that your collection is defined and populated before iterating to prevent runtime rendering crashes.
• Use Iterator for Edge Cases: If you need to style the first or last item differently (e.g., omitting commas or borders), use the iterator:it directive instead of for:each.

Summary

Mastering list iteration with for:each is a fundamental building block for creating dynamic Lightning Web Components in Salesforce. By pairing clean array structures with unique key attributes, developers can build responsive, high-performance UI components that update seamlessly.