Expand groups into entities: expand

The expand template function takes groupsGroups are a way to organize your entities into a single unit. [Learn more], zonesZones allow you to specify certain regions on a map. They enable zone presence-detection and can be used in automations. For example, to start the vacuum after you left home or start the heating at home when you leave the office. [Learn more], or lists of entity IDs and expands them into a flat, sorted list of individual entityAn 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] state objects. If you pass in a group, it gives you all the individual entities that belong to that group, with duplicates removed.

This is extremely useful when you want to work with a collection of entities. For example, you might have a group of temperature sensorsSensors return information about a thing, for instance the level of water in a tank. [Learn more] and want to calculate the average, find the highest reading, or count how many are above a threshold. The result is sorted alphabetically by entity ID and contains full state objects, so you can access .state, .entity_id, .attributes, and .last_changed on each one.

Usage

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

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

[
  "light.living_room_ceiling",
  "light.living_room_lamp",
  "light.living_room_strip",
]

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

[
  "light.living_room_ceiling",
  "light.living_room_lamp",
  "light.living_room_strip",
]

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.

expand(
    *args: str | State | list,
) -> list[State]

Function parameters

The following parameters can be provided to this function.

Good to know

• Returns full state objects, not entity IDs. Add | map(attribute="entity_id") to get IDs.
• Entities that do not exist are silently dropped from the result.
• The result is sorted by entity ID and has duplicates removed.
• Nested groups are expanded recursively, so you get every individual entity in the end.

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.

Count how many lights are on in a group

{{
  expand("group.all_lights")
  | selectattr("state", "eq", "on")
  | list
  | count
}}

5

Calculate average temperature from a group

Combine expand with average to get the mean temperature across a group of sensors.

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

21.3

Find the entity with the highest value

{{
  expand("group.temperature_sensors")
  | sort(attribute="state", reverse=true)
  | map(attribute="entity_id")
  | first
}}

sensor.kitchen_temperature

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:

• Get entity state: states - Returns the state value of an entity, or lets you iterate over all entity states.

• Test entity state: is_state - Tests if an entity is in a specific state.

• Get entities in an area: area_entities - Returns a list of entity IDs associated with a given area.