Repeating a Template

Repeating a Template

A template removes the repetition inside a card. for_each removes the repetition around it — one card renders the template once per item in a list, instead of you pasting the same instance block out four times.

type: custom:decluttering-card-plus
template: room_tile
columns: 2
variables:
  - colour: amber
for_each:
  - entity: light.kitchen
    name: Kitchen
  - entity: light.hall
    name: Hall
  - entity: light.shed
    name: Shed
    colour: blue

Three tiles, two columns, from one card.

---

Items

Each item holds the variables for that copy, written as a mapping — which reads better than a list of one-key entries when every copy sets the same few things:

for_each:
  - entity: light.kitchen
    name: Kitchen

A list of one-key entries works too, if you prefer it to match variables::

for_each:
  - - entity: light.kitchen
    - name: Kitchen

A for_each that is a single mapping rather than a list counts as a list of one, the same forgiveness variables: gets — and an empty mapping counts as no list at all, so a cleared field never leaves a stray single-copy stack behind.

Sharing values between copies

Anything in the card's own variables: is shared by every copy, and an item can override it. Above, colour is amber everywhere except the shed.

That is the usual shape: put what is the same in variables:, and what differs in for_each.

Repeating over what Home Assistant knows (v1.1.0+)

Writing the list out means the dashboard stops being true the moment a lamp is added. for_each_from asks Home Assistant instead, so the card grows by itself:

type: custom:decluttering-card-plus
template: room_light
columns: 2
for_each_from:
  domain: light
  area: Kitchen

Repeat over entities or over areas, and narrow by domain, area, floor or label. Each copy is given the things it needs — the entity id, its name, the area it is in — and the list is worked out again when the registry changes, not on every state change.

A written-out for_each wins over for_each_from if a card somehow has both: it is the more particular of the two.

---

Numbering the copies (v1.1.0+)

Every copy is also given [[index]], counting from one, and [[count]], the number of copies — so a template can number itself without you writing the number into each item:

card:
  type: markdown
  content: 'Room [[index]] of [[count]]'

An item that sets index or count itself wins, so a template already using those names for something else keeps working.

---

Leaving out a copy that has nothing to show (v1.1.0+)

for_each skips an item that leaves a required: true variable empty, which is what lets one template serve a room with four lights and a room with one:

type: custom:decluttering-template-plus
template: room_light
variables:
  - name: entity
    required: true
card:
  type: tile
  entity: '[[entity]]'

type: custom:decluttering-card-plus
template: room_light
columns: 4
for_each:
  - entity: light.kitchen
  - entity: light.hall
  - entity: ''
  - {}

That renders two cards, not four, with no gaps where the other two would have been. A template that requires nothing renders every item as before. See Describing Variables for required.

---

Layout

columns	Result
absent, or 1	The copies stack vertically
2 or more	The copies are laid out in that many columns
with min_column_width	columns becomes the most it will use; a column is dropped rather than going narrower

The copies are handed to Home Assistant's own vertical-stack and grid cards, so they behave exactly like any other card in your layout — including in the sections layout, and including visibility conditions on each copy.

---

What it needs

for_each needs a template that defines a card. A row, badge or element has nothing to stack, and asking for one is an error:

for_each needs a template that defines a card

An empty list renders nothing rather than failing the card, so a list you build up over time can start out empty without breaking the dashboard.

A style on the card resolves against the card's own variables and the template's declared defaults, not any one item's values — per item it would be ambiguous.

---

In the editor

For a card template, the card editor offers Repeat for each and Columns below the variables.

The missing-variable warning accounts for the items, so a card whose for_each supplies entity and name is not told they are missing. See Describing Variables.

---

When not to use it

If the copies differ by more than a few values — different card types, different structure — you want separate cards, or a template with visibility conditions inside it. for_each is for the case where the only thing that changes is what you pass in.

---

Reference

Key	Type	Description
for_each	list	One copy of the template per item; each item is that copy's variables. A single mapping counts as a list of one
columns	number	How many copies sit side by side. Defaults to 1
min_column_width (v1.1.0+)	number	Pixels. Drops a column rather than going narrower, so one card suits a phone too
for_each_from (v1.1.0+)	mapping	What to repeat over, read from Home Assistant instead of written out

---

Next

→ Using Templates · Describing Variables → Recipes for finished examples