Jinja Items: filter function to iterate over key-value pairs

The Jinja `items` Filter

nThe Jinja items filter is a simple yet crucial tool for working with dictionaries (or mappings). Its primary purpose is to return an iterator over the key-value pairs of a dictionary, making it easy to loop through both the keys and their corresponding values in a for loop. While you can often achieve the same result using the .items() method directly on a dictionary, the items filter provides an added layer of safety by gracefully handling Undefined values without raising an error. This makes your templates more robust and portable across different Jinja implementations.nn

How the `items` Filter Works

nThe items filter takes a dictionary as input and returns an iterator of (key, value) tuples. This is identical to how Python’s built-in .items() method works.nnThe basic syntax is:n

{% for key, value in my_dict | items %}n    <p>Key: {{ key }}, Value: {{ value }}</p>n{% endfor %}

nThe key advantage of using the items filter over the .items() method is its handling of Undefined values. If my_dict is not defined, my_dict | items will simply return an empty iterator, preventing a jinja2.exceptions.UndefinedError from crashing your template. This makes your code more resilient to missing or optional data.nn

Practical Examples

nLet’s look at some examples to see how the items filter can be used effectively.n

Example 1: Iterating Through a Simple Dictionary

nThis is the most common use case, allowing you to access both the key and value of a dictionary in a single loop.nnPython Code:n

# 'user_profile' is passed to the templatenuser_profile = {n    'username': 'jinja_dev',n    'status': 'online',n    'last_login': '2025-08-11'n}

nJinja Template:n

<h3>User Profile</h3>n<dl>n    {% for key, value in user_profile | items %}n        <dt>{{ key | capitalize | replace('_', ' ') }}</dt>n        <dd>{{ value }}</dd>n    {% endfor %}n</dl>

nRendered HTML:n

<h3>User Profile</h3>n<dl>n    <dt>Username</dt>n    <dd>jinja_dev</dd>n    <dt>Status</dt>n    <dd>online</dd>n    <dt>Last login</dt>n    <dd>2025-08-11</dd>n</dl>

nThe items filter allows you to access key and value simultaneously, which is perfect for building descriptive lists like this.n

Example 2: Handling Undefined Values with Grace

nImagine a scenario where a dictionary might not be present. The items filter will prevent your template from failing.nnPython Code:n

# 'user_settings' might be None or not passed to the template at allnuser_settings = None

nJinja Template:n

{% if user_settings | items %}n    <h3>User Settings</h3>n    <ul>n        {% for key, value in user_settings | items %}n            <li>{{ key }}: {{ value }}</li>n        {% endfor %}n    </ul>n{% else %}n    <p>No user settings found.</p>n{% endif %}

nRendered HTML:n

<p>No user settings found.</p>

nIn this case, user_settings | items returns an empty iterator, causing the if condition to fail. The template then renders the fallback message, avoiding a runtime error. This is a crucial safety feature that the direct .items() method lacks.nn

Conclusion

nThe Jinja items filter is a valuable addition to the developer’s toolkit, especially when you need to iterate through dictionaries safely and predictably. Its ability to return an empty iterator for Undefined values makes it more robust than the direct .items() method, leading to more resilient templates. This filter, introduced in Jinja 3.1, is a testament to the library’s ongoing efforts to provide clean, safe, and powerful tools for template development.nn

Jinja Items: filter function to iterate over key-value pairs

The Jinja items Filter

How the items Filter Works