Transform list items: map

The map filter applies a transformation to each item in a list and returns the results. It can be used in two primary ways: extracting an attribute from each item using attribute=, or applying another filter to each item by passing the filter name as a string. This is a Home Assistant override of the standard map filter, extended to support additional Home Assistant-specific filters and type conversions.

This is one of the most heavily used filters in Home Assistant templates. You will find it in almost every template that works with a collection of 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]. The attribute= form extracts values like .state, .entity_id, or .name from entity state objects returned by expand. The filter form lets you apply conversions like float, int, or round to each item in a list, so you can build filter chains that transform raw entity data into useful results.

Usage

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

{{ expand("group.temperature_sensors") | map(attribute="state") | list }}

["21.5", "19.8", "22.3"]

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.

map(
    value: list,
    *args: str,
    attribute: str | None = None,
    default: Any = None,
) -> iterable

Function parameters

The following parameters can be provided to this filter.

Extract an attribute from each item

Use attribute= to pull a specific property from each item in the list.

{{
  expand("group.all_lights")
  | map(attribute="entity_id")
  | list
}}

["light.bedroom", "light.kitchen", "light.living_room"]

Apply a filter to each item

Pass a filter name as a string to apply it to every item in the list.

{{
  ["21.5", "19.8", "22.3"]
  | map("float")
  | list
}}

[21.5, 19.8, 22.3]

Nested attribute access

Use dotted notation to access nested attributes.

{{
  expand("group.all_lights")
  | selectattr("state", "eq", "on")
  | map(attribute="attributes.brightness")
  | list
}}

[255, 128, 64]

Good to know

• Returns an iterable, not a list. Add | list before using it with length, first, or looping twice.
• attribute= extracts a property; a filter name as the first positional argument applies that filter to each item. You can use one or the other, not both.
• Missing attributes default to None unless you pass default=.

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.

Calculate average temperature from a group

Extract state values, convert to floats, and compute the average.

{{
  expand("group.temperature_sensors")
  | map(attribute="state")
  | map("float")
  | average
}}

21.2

Get friendly names of all entities in a group

{{
  expand("group.all_lights")
  | map(attribute="name")
  | list
}}

["Bedroom light", "Kitchen light", "Living room light"]

Chain map with round for clean display

Apply multiple transformations by chaining map calls.

{{
  expand("group.temperature_sensors")
  | map(attribute="state")
  | map("float")
  | map("round", 1)
  | list
}}

[21.5, 19.8, 22.3]

Apply string filters to a list

Use map to apply string transformations to every item.

{{
  ["hello", "world", "template"]
  | map("upper")
  | list
}}

["HELLO", "WORLD", "TEMPLATE"]

Default value for missing attributes

Use default= to handle items that may not have the requested attribute.

{{
  expand("group.all_lights")
  | map(attribute="attributes.brightness", default=0)
  | list
}}

[255, 0, 128]

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:

• Filter items by test: select - Filters a list, keeping only items that pass a given test.

• Filter items by attribute test: selectattr - Filters a list, keeping only items where a specified attribute passes a test.

• Expand groups into entities: expand - Expands groups and zones into a sorted list of individual entity state objects.

• Sort a list: sort - Sorts the items in a list, with optional attribute-based and reverse sorting.