Decluttering Card Plus Contents ↓ GitHub ↗

How It Fits Together

What the pieces are called, what each one is for, and where to read more. This page does not teach any one thing in detail; it is the map. If you have used the card for a while and keep hunting for where something lives, the table at the end is for you.

Templates and the cards that use them

Everything starts with two things:

decluttering_templates:          # the template
  room_light:
    card:
      type: tile
      entity: '[[light]]'
      name: '[[room]]'

# ...and on a view, a card that uses it
type: custom:decluttering-card-plus
template: room_light
variables:
  light: light.kitchen_ceiling
  room: Kitchen

When the card builds, it takes the template, fills every placeholder, and shows what comes out, exactly as if you had written the tile yourself. Change the template and every card using it changes.

More: Quick Start, Defining Templates, Using Templates.

Where templates live

Where Written as Good for
The dashboard’s decluttering_templates: YAML in the raw configuration editor The usual place: every template in one block
A template card custom:decluttering-template-plus on a view, shown only in edit mode Editing a template visually, next to the cards using it
Another dashboard decluttering_templates_from: names it One set of templates for several dashboards
The library dashboard a dashboard at the path decluttering-templates Templates every dashboard gets without asking

Templates you install from the shared collection or the built-in examples end up in one of the first two. More: Defining Templates, Sharing Templates Between Dashboards, Sharing a Template.

What a template can build

A template holds exactly one kind of thing, named by its key, and that decides where a card using it can go.

Key Builds A card using it goes
card: a card anywhere a card goes
badge: a badge in a view’s badges:
row: a row in an Entities card’s entities:
element: an element in a Picture Elements card’s elements:
group: several cards (or badges), laid out as if each were written there anywhere a card goes
item: a block for a list inside another template nowhere on its own: [[name|with:…]] and [[name|repeat:…]] use it

The same custom:decluttering-card-plus type is used in every one of those places. More: Cards, Badges, Rows, Elements, List Entries.

Strategies are different: they are not templates, but they build whole sections, badges or views from a description, repeating some of them. A view strategy writes a view; a dashboard strategy writes a whole dashboard. Templated cards inside them work as usual. More: Repeating Sections and Badges.

Where values come from

A placeholder’s value can come from several places. They have different jobs:

Written Key Who sets it Can the card change it? Use it for
on the card variables: whoever adds the card it is the card what differs from card to card: the entity, the room
in the template default: (or defaults:) the template’s author yes a sensible value when the card says nothing
in the template let: the template’s author no values worked out from the others: light.[[room\|slug]]_ceiling
on the dashboard, a view or a section decluttering_defaults: whoever owns the dashboard yes house-wide choices: the accent colour, this view’s room
on the dashboard, a view or a section decluttering_let: whoever owns the dashboard no values worked out the same way for every card

One more key looks similar but is not a value at all:

Written Key What it is
in the template variables: declarations: a description of each variable (its label, the control the editor shows, whether it is required). Not values
on the dashboard decluttering_variables: declarations shared by every template

So variables: means values on a card and descriptions in a template. A declaration can carry a default: of its own, which counts as a default.

When several give the same name a value, the order is: let first (nobody can override it), then the card’s variables:, then defaults, the nearest first (section, view, template, dashboard). The full order is on Placeholder Reference.

More: Variables, Describing Variables.

Placeholders and steps

A placeholder is [[name]]. Steps after a bar change what it gives:

You want Write Gives
the value as it is [[room]] back garden
the value reshaped [[room\|title]] Back Garden
a stand-in when nothing is set [[room\|default:Somewhere]] Somewhere
the option gone when nothing is set [[icon?]] no icon: key at all
something Home Assistant knows [[light\|area]] Kitchen
a little arithmetic [[index\|mul:12]] 36
a yes or no [[compact\|bool]] true

Steps run left to right and chain: [[light|friendly_name|upper]]. Every step, with an example of each, is on Placeholder Reference. To see what a chain gives without touching a dashboard, use Try a placeholder.

More: Variables.

Repeating

Four ways to get many of something from one template. The first three use the same for_each and for_each_from keys; the fourth, repeat:, reads a variable holding a list or a for_each_from mapping.

You want Use Where it goes Page
a card per item, in one card’s space for_each / for_each_from on a custom:decluttering-card-plus card anywhere a card goes Repeating a Template
a section or a badge per item a view strategy a view’s strategy: Repeating Sections and Badges
a whole view per item a dashboard strategy the dashboard’s strategy: Repeating Sections and Badges
an entry per item inside a card’s own list (rows of an Entities card, buttons of a stack) [[name\|repeat:list]] in the template’s content List Entries

for_each repeats over a list you write out. for_each_from repeats over what Home Assistant knows: entities matching a pattern, areas, devices, floors, labels, the dashboard’s views, or a list a Jinja template works out. Each copy is given values of its own (entity, name, area, index…). Every key is on Repeat Reference.

A repeat is worked out when the card builds, and again when Home Assistant’s registries change (entities, devices, areas, floors, labels, categories). It is not live on every state change; for that, see rebuild_on.

Variations without a new template

You want Use Page
one card slightly different from the template card: (or badge:…) on that card, laid over what it builds Using Templates
a family of templates sharing most of their content extends: on the template Defining Templates
a different template depending on the entity’s domain template_by_domain: on the card Using Templates
an option on only when a variable says so [[x\|if:other]], [[x?]], [[x\|bool]] Variables
a card that hides itself Home Assistant’s visibility: on the card Visibility
a template inside a template a custom:decluttering-card-plus in the template’s content, with inherit_variables: true to pass everything down Defining Templates

When the card builds

The card fills in its template when the dashboard loads, when you edit it, and when what it reads from Home Assistant’s registries changes (an entity renamed, a device moved to another area). It does not build again on every state change: a tile shows a live state because the tile reads it, not because the template was filled in again.

When a template needs to change shape with a state (show a different card when the house is in Away mode), list that entity in rebuild_on: on the card, and read it with [[input_select.house_mode|state]]. More: Following an entity’s state.

Tools

Tool What it does Page
The card editor Pick a template and fill in its variables with proper controls Visual Editors
The template editor Edit a template, see where it is used, rename, share, check the dashboard’s health Visual Editors
Template builder Paste cards you already have and get the template they are copies of Trying It Out
Try a placeholder See what each step of a chain gives, in the browser Trying It Out
debug: on a card Shows or logs what the card built and where every value came from Troubleshooting

Where to find things

Looking for Go to
a key you half remember the A to Z, or the search box on the docs site
every key of the dashboard, a template, a declaration or the card Configuration Reference
every [[placeholder\|step]], what it gives, what it does with an empty value Placeholder Reference
every for_each_from key, and what each copy is given Repeat Reference
which value wins when several are set Placeholder Reference
how to write a template Defining Templates
what goes on the card using it Using Templates
how values, defaults and let work Variables
making a template easy for others to fill in Describing Variables
a ready-made answer to a common problem Recipes
why something is not working Troubleshooting