Split list into batches: batch

The batch filter splits a list into smaller sub-lists (batches) of a given size. If the last batch has fewer items than the requested size, you can optionally provide a fill value to pad it.

This is useful when you need to process or display items in fixed-size groups. For example, you might want to display entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] in rows of three on a dashboard, create notification messages that include a limited number of items per message, or iterate through a large list of devicesA device is a model representing a physical or logical unit that contains entities. in manageable chunks.

Usage

Here’s how to use this template function. Copy any example and adjust it to your setup.

{{ [1, 2, 3, 4, 5] | batch(2) | list }}

[[1, 2], [3, 4], [5]]

Function signature

The signature is a technical summary of this template function. It shows the name of the function, the values (called parameters) it accepts, and what type of data each parameter expects (for example, a piece of text or a number).

Function parameters that have a = with a value after them are optional. If you leave them out, the default value shown is used automatically. Function parameters without a default are required.

batch(
    value: list,
    linecount: int,
    fill_with: Any = None,
) -> list[list]

Function parameters

The following parameters can be provided to this filter.

Padding the last batch

Use the fill_with parameter to pad the last batch so all batches have the same number of items.

{{ [1, 2, 3, 4, 5] | batch(3, "N/A") | list }}

[[1, 2, 3], [4, 5, "N/A"]]

Good to know

• Returns a generator, so add | list before using it with length or iterating twice.
• Without fill_with, the last batch can be smaller than the requested size.
• The batch size must be a positive integer. Passing zero raises an error.

Try it yourself

Ready to test this? Open Developer tools > Template, paste the example into the Template editor, and watch the result update on the right. Edit the values to see how the function adapts to your own entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this function comes up in automations and templates. Copy any example and adapt it to your setup.

Display entities in rows

Split a list of entity states into rows of three for a formatted display.

{% set lights = ["light.kitchen", "light.bedroom", "light.hall",
                 "light.porch", "light.garage"] %}
{% for row in lights | batch(3) %}
  Row {{ loop.index }}: {{ row | join(", ") }}
{% endfor %}

Row 1: light.kitchen, light.bedroom, light.hall
Row 2: light.porch, light.garage

Process devices in chunks

Iterate through a large list of items in manageable batches.

{% set items = range(10) | list %}
{% for chunk in items | batch(4) %}
  Batch {{ loop.index }}: {{ chunk | join(", ") }}
{% endfor %}

Batch 1: 0, 1, 2, 3
Batch 2: 4, 5, 6, 7
Batch 3: 8, 9

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with your template and expected result, or share on our subreddit /r/homeassistant.

Related template functions

These functions work well alongside this one:

• Slice a list into sub-lists: slice - Slices a list into a specified number of sub-lists of roughly equal size.

• Group items by attribute: groupby - Groups a list of items by a common attribute, producing a list of (grouper, list) pairs.

• Flatten nested lists: flatten - Flattens nested lists into a single flat list.