4 Loop over each item in a sequence. For example, to display a list of users
5 provided in a variable called ``users``:
11 {% for user in users %}
12 <li>{{ user.username|e }}</li>
18 A sequence can be either an array or an object implementing the
19 ``Traversable`` interface.
21 If you do need to iterate over a sequence of numbers, you can use the ``..``
30 The above snippet of code would print all numbers from 0 to 10.
32 It can be also useful with letters:
36 {% for letter in 'a'..'z' %}
40 The ``..`` operator can take any expression at both sides:
44 {% for letter in 'a'|upper..'z'|upper %}
50 If you need a step different from 1, you can use the ``range`` function
56 Inside of a ``for`` loop block you can access some special variables:
58 ===================== =============================================================
60 ===================== =============================================================
61 ``loop.index`` The current iteration of the loop. (1 indexed)
62 ``loop.index0`` The current iteration of the loop. (0 indexed)
63 ``loop.revindex`` The number of iterations from the end of the loop (1 indexed)
64 ``loop.revindex0`` The number of iterations from the end of the loop (0 indexed)
65 ``loop.first`` True if first iteration
66 ``loop.last`` True if last iteration
67 ``loop.length`` The number of items in the sequence
68 ``loop.parent`` The parent context
69 ===================== =============================================================
73 {% for user in users %}
74 {{ loop.index }} - {{ user.username }}
79 The ``loop.length``, ``loop.revindex``, ``loop.revindex0``, and
80 ``loop.last`` variables are only available for PHP arrays, or objects that
81 implement the ``Countable`` interface. They are also not available when
82 looping with a condition.
85 The ``if`` modifier support has been added in Twig 1.2.
90 Unlike in PHP, it's not possible to ``break`` or ``continue`` in a loop. You
91 can however filter the sequence during iteration which allows you to skip
92 items. The following example skips all the users which are not active:
97 {% for user in users if user.active %}
98 <li>{{ user.username|e }}</li>
102 The advantage is that the special loop variable will count correctly thus not
103 counting the users not iterated over. Keep in mind that properties like
104 ``loop.last`` will not be defined when using loop conditions.
108 Using the ``loop`` variable within the condition is not recommended as it
109 will probably not be doing what you expect it to. For instance, adding a
110 condition like ``loop.index > 4`` won't work as the index is only
111 incremented when the condition is true (so the condition will never
117 If no iteration took place because the sequence was empty, you can render a
118 replacement block by using ``else``:
120 .. code-block:: jinja
123 {% for user in users %}
124 <li>{{ user.username|e }}</li>
126 <li><em>no user found</em></li>
133 By default, a loop iterates over the values of the sequence. You can iterate
134 on keys by using the ``keys`` filter:
136 .. code-block:: jinja
140 {% for key in users|keys %}
145 Iterating over Keys and Values
146 ------------------------------
148 You can also access both keys and values:
150 .. code-block:: jinja
154 {% for key, user in users %}
155 <li>{{ key }}: {{ user.username|e }}</li>
159 Iterating over a Subset
160 -----------------------
162 You might want to iterate over a subset of values. This can be achieved using
163 the :doc:`slice <../filters/slice>` filter:
165 .. code-block:: jinja
167 <h1>Top Ten Members</h1>
169 {% for user in users|slice(0, 10) %}
170 <li>{{ user.username|e }}</li>