Get devices with a label: label_devices

The label_devices template function returns a list of deviceA device is a model representing a physical or logical unit that contains entities. IDs that have a specific labelLabels in Home Assistant allow grouping elements irrespective of their physical location or type. Labels can be assigned to areas, devices, entities, automations, scenes, scripts, and helpers. Labels can be used in automations and scripts as a target for actions. Labels can also be used to filter data. [Learn more] assigned. You can specify the label by its name or by its internal ID. This gives you all devices tagged with that label.

This is useful when you organize your devices using labels and want to act on or inspect a specific group. For example, if you label battery-powered devices as “Battery”, you could use label_devices to find them all and check their battery levels, or if you label certain devices as “Guest Room”, you could quickly find and control all devices for your guests. As you add or remove labels from devices, the list automatically updates, so your automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] and templatesA template is an automation definition that can include variables for the action or data from the trigger values. This allows automations to generate dynamic actions. [Learn more] always reflect the current state.

Usage

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

{{ label_devices("Battery") }}

[
  "a1b2c3d4e5f6a1b2c3d4e5f6",
  "f6e5d4c3b2a1f6e5d4c3b2a1",
]

{{ "Battery" | label_devices }}

[
  "a1b2c3d4e5f6a1b2c3d4e5f6",
  "f6e5d4c3b2a1f6e5d4c3b2a1",
]

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.

label_devices(
    label_id_or_name: str,
) -> list[str]

Function parameters

The following parameters can be provided to this function.

Good to know

• Only returns devices with the label assigned directly. Labels applied to entities or areas do not roll up to their devices.
• Returns an empty list when the label does not match any devices.

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 devices with a specific label

Find out how many devices are tagged with a given label.

{{ label_devices("Battery") | count }}

2

Get device names for a label

List the friendly names of all devices that have a specific label by combining label_devices with device_name.

{% for device_id in label_devices("Battery") %}
  {{ device_name(device_id) }}
{% endfor %}

Living Room Motion Sensor
Front Door Sensor

Check battery levels of labeled devices

Find all devices with a “Battery” label and check their battery sensor entities. This collects the battery-level entities for all labeled devices.

{% for device_id in label_devices("Battery") %}
  {% set batteries = device_entities(device_id)
    | select("match", "sensor.")
    | select("search", "battery")
    | list %}
  {% for entity_id in batteries %}
    {{ device_name(device_id) }}: {{ states(entity_id) }}%
  {% endfor %}
{% endfor %}

Living Room Motion Sensor: 85%
Front Door Sensor: 42%

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 areas with a label: label_areas - Returns a list of area IDs that have a specific label assigned.

• Get entities with a label: label_entities - Returns a list of entity IDs that have a specific label assigned.

• Get all labels: labels - Returns a list of all label IDs, or the labels assigned to a specific entity, device, or area.

• Get label ID: label_id - Returns the label ID for a given label name.

• Get label name: label_name - Returns the friendly name of a label from its ID.