Using th:each in Thymeleaf

October 18, 2019 No comments Thymeleaf Attribute Iteration th:each

1. Overview

Thymeleaf is a Java-based template engine used for processing HTML, XML, JS, and many other web documents. In this tutorial, we will show you how to use th:each attribute for iteration over values in Thymeleaf.

If you need some more information about how to start with Thymeleaf just take a look at our introduction article here.

2. Iteration attribute th:each

Thymeleaf used th:each attribute to iterate over collection items. There are several objects that Thymeleaf considered as iterable:

  • objects implementing java.util.Iterable interface,
  • objects implementing java.util.Enumeration interface,
  • objects implementing java.util.Iterator iterface,
  • objects implementing java.util.Map interface,
  • array objects.

For the sake of example let's assume that we want to display a list of customers in a simple HTML table.

In our example Customer object will have the following structure:

package com.frontbackend.thymeleaf.customers.model;

import java.util.List;

import lombok.Data;

public class Customer {

    private String firstName;
    private String lastName;
    private String email;
    private int age;
    private List<Address> addressList;


Address list in the Customer object is added to showcase how to iterate over nested lists in Thymeleaf templates.

In this case Address will contain the following attributes:

package com.frontbackend.thymeleaf.customers.model;

import lombok.Data;

public class Address {

    private String street;
    private String city;
    private String zip;
    private String state;


We will use th:each to iterate through the list of customers and list of addresses for each customer.

Thymeleaf template, that we used in this example, will list all customer information like: firstName, lastName, age, email with the number of row in table. Additionally we present all address data (street, city, zip, state) for each customer. This template have the following structure:

<html lang="en" xmlns:th="">
    <meta charset="UTF-8"/>
    <title>Spring Boot Thymeleaf Application</title>
<h1>List of Customers</h1>
        <th>First Name</th>
        <th>Last Name</th>
        <th>Address list</th>
    <tr th:each="customer, custStat : ${customers}">
        <td th:text="${custStat.count}">1</td>
        <td th:text="${customer.firstName}">John</td>
        <td th:text="${customer.lastName}">Doe</td>
        <td th:text="${customer.age}">18</td>
        <td th:text="${}"></td>
            <p th:each="address : ${customer.addressList}">
                <span th:text="${address.street}">Street</span>
                <span th:text="${}">City</span>
                <span th:text="${}">ZIP</span>
                <span th:text="${address.state}">State</span>

Thymeleaf engine will repeat fragment of the template that contains th:each attribute (in this case the tr.../tr element) for each element in the iterable collection.

3. Iteration status

Thymeleaf provides a special status object that gives some useful information about the iteration process.

The status object contains the following information:

  • iteration index, starting from 0 - the ${custStat.index} property,
  • iteration index, starting from 1 - the ${custStat.count} property.
  • total amount of elements in the iterated variable - the ${custStat.size} property.
  • iter variable for each iteration - the ${custStat.current} property.
  • Whether the current iteration is even or odd. These are the ${custStat.even} and ${custStat.odd} boolean properties.
  • Whether the current iteration is the first one. This is the ${custStat.first} boolean property.
  • Whether the current iteration is the last one. This is the ${custStat.last} boolean property.

4. Conclusion

In this article, we presented how iterations in Thymeleaf work. We explained th:each attribute using a simple real-life example.

Working application with code shown in this article is available in our GitHub Repository.

{{ message }}

{{ 'Comments are closed.' | trans }}