Decluttering Card Plus Contents ↓ GitHub ↗

Configuration Reference

Every option, in one place.

Dashboard root

Keys that go at the top level of a dashboard’s configuration, alongside views:.

Key Type Description
decluttering_templates mapping Template definitions, keyed by name. See Defining Templates.
decluttering_templates_from list of strings, or a single string URL paths of dashboards to borrow templates from. See Sharing Templates Between Dashboards.
decluttering_defaults (v1.1.0+) mapping, or a list Values every template on this dashboard falls back on, reached last of all 
decluttering_templates:
  room_light:
    card:
      type: tile
      entity: '[[light]]'

decluttering_templates_from:
  - shared-templates

decluttering_defaults:
  colour: amber

views: []

The raw configuration editor showing all three root keys

The same keys in the raw configuration editor, which is where a dashboard in storage mode is edited: ⋮ → Raw configuration editor.

Template definition

Whether written under decluttering_templates or as a decluttering-template-plus card.

Key Type Required Description
card mapping one of these four A card
badge mapping one of these four A badge
row mapping one of these four An Entities card row
element mapping one of these four A Picture Elements element
description string — What the template is for. Shown to whoever uses it.
variables list — Descriptions of the variables it takes. See Describing Variables.
default list, or a mapping — Fallback variable values. See Variables.
style string — CSS to inject. See Styling.

Exactly one of card, badge, row, element. Any other combination is an error:

You must define one card, badge, element, or row in the template

custom:decluttering-template-plus

Defines a template as a card. Visible only in edit mode.

Key Type Required Description
type string ✅ custom:decluttering-template-plus
template string ✅ The template’s name
card / badge / row / element mapping ✅ (one) The content
description string — What the template is for
variables list — Variable declarations
default list, or a mapping — Fallback variable values
style string — CSS to inject 
type: custom:decluttering-template-plus
template: room_light
card:
  type: tile
  entity: '[[light]]'
  name: '[[room]]'
default:
  - light: light.living_room
  - room: Living Room

custom:decluttering-card-plus

Uses a template.

Key Type Required Description
type string ✅ custom:decluttering-card-plus
template string ✅ Name of the template to use
variables list, or a mapping — Values to substitute
for_each list — Render the template once per item. Card templates only. See Repeating a Template.
for_each_from (v1.1.0+) mapping — What to repeat over, read from Home Assistant rather than written out
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
gap (v1.2.0+) number — Pixels between repeated copies. Leave out for Home Assistant’s own spacing
empty (v1.2.0+) card — What to render when a repeat produces no copies
grid_options (v1.2.0+) mapping — How much of a sections grid to ask for. Beats the template’s
debug (v1.2.0+) boolean — Render what the card builds instead of the card. See Troubleshooting
strict (v1.2.0+) boolean — Refuse rather than render a variable nothing set
fit (v1.1.0+) string — box (default) keeps a box of its own; contents gives it up. See Styling
style string — Extra CSS, appended after the template’s
style mapping — In a Picture Elements card only, this is the element’s position. See Elements.
visibility list — Standard Home Assistant conditions, applied to this card 
type: custom:decluttering-card-plus
template: room_light
variables:
  - light: light.kitchen
  - room: Kitchen

Inside for_each_from (v1.1.0+)

Key Type Description
entities string, list or true Repeat over entities matching these id patterns. The default when areas is absent
areas string, list or true Repeat over areas matching these patterns
range (v1.2.0+) number Repeat this many times, with only the position to go on
domain string or list Narrows to entities of these domains
device_class (v1.2.0+) string or list Narrows to entities reporting these device classes
integration (v1.2.0+) string or list Narrows to entities from these integrations
area string or list Narrows to these areas, by name or id
floor string or list Narrows to these floors, by name or id
label string or list Narrows to things carrying these labels, by name or id
exclude (v1.2.0+) string, list or mapping What to leave out. Patterns mean entity ids; a mapping narrows by anything above
sort (v1.2.0+) string name, entity, id, area, domain, floor. Anything else keeps the registry order
reverse (v1.2.0+) boolean Turns whichever order was chosen around
limit (v1.2.0+) number At most this many copies. total still reports what matched
with (v1.2.0+) mapping For an area source: the entities to gather for each area, plus keep_empty

What every copy is given

Name From Is
index, count any repeat Position counted from one, and how many
index0, first, last (v1.2.0+) any repeat Position from zero, and whether this is an end
entity, name, domain, area, area_id an entity source The entity and where it lives
area_id, area, area_icon, floor an area source The area and its floor
total (v1.2.0+) a registry source What matched before limit
items, entities, entity_count (v1.2.0+) an area source with with What is in that area

Variable declaration

One entry of a template’s variables: list.

Key Type Required Description
name string ✅ The variable’s name, as written in [[name]]
label string — What the editor calls it. Defaults to the name
description string — Helper text under the control
selector mapping — Any Home Assistant selector. Defaults to a text box
default any — The value to use when a card does not set one

Variable syntax

Form Behaviour
'[[name]]' as an entire value Substituted with the value, type preserved (number, boolean, mapping, list, null)
[[name]] inside a longer string Substituted as text
[[name|slug]] Lower case, non-alphanumeric runs become _
[[name|upper]] / [[name|lower]] Case changed
[[name|title]] Each word capitalised
[[name|kebab]] (v1.1.0+) Lower case, non-alphanumeric runs become -
[[name|json]] (v1.2.0+) The value as its JSON text. The one step that takes a mapping or a list
[[name|friendly_name]] etc (v1.1.0+) Asks Home Assistant. Also area, device, attr:<name>
[[name|floor]], [[name\|area_id]], [[name\|device_id]] (v1.2.0+) The floor, and the ids behind the names
[[name|default:Text]] (v1.2.0+) That text when nothing set the variable
[[name|or:other]] (v1.2.0+) Another variable’s value when nothing set this one
[[name?]] (v1.1.0+) The key is removed entirely when nothing set it
[[!name]] (v1.1.0+) The literal text [[name]]
[[a.b]] (v1.2.0+) Reaches into a nested mapping, three levels deep
Any other word after the bar Not a transform; left in place
No matching variable or default Left in place as literal [[name]]

Steps chain, left to right: [[room|or:name|default:Somewhere|slug|upper]]. A resolver reads its value as an entity id, so it has to come before anything reshapes it.

A transformed placeholder is always text, whatever the value’s own type.

Precedence Winner
variables on the card vs any default variables
default inside a declaration vs the default: list the declaration
Same key listed twice the first

Substitution repeats until nothing changes, to a maximum of 10 passes. A self-referencing variable stops there with a console warning. A template that uses itself is refused outright (v1.2.0+) — see Troubleshooting.

Full detail: Variables.

Host classes

Applied to the wrapper element, for use in style.

Class Applied to
decluttering-container Card, row and element templates
decluttering-badge Badge templates
decluttering-card Card templates only
decluttering-fit-contents (v1.1.0+) A card set to fit: contents
child-card-hidden A card hidden by its own visibility conditions

Registered card types

Type Purpose
custom:decluttering-card-plus Use a template
custom:decluttering-template-plus Define a template
custom:decluttering-card Compatibility alias, when the original card is not installed
custom:decluttering-template Compatibility alias, when the original card is not installed

See Migrating from decluttering-card.

Error messages

Message Meaning
Missing template object in your config No template: on the card
Missing template property No template: on the template card
You must define one card, badge, element, or row in the template Zero, or more than one, content key
for_each needs a template that defines a card for_each used with a row, badge or element template
The template "…" doesn't exist in decluttering_templates or in a custom:decluttering-template card Name not found, and no borrowing configured
The template "…" doesn't exist in decluttering_templates, in a custom:decluttering-template card, or on any dashboard listed in decluttering_templates_from Name not found anywhere, including borrowed dashboards
Could not retrieve the lovelace configuration. The card could not find the dashboard config — see Troubleshooting
Could not resolve the template "…": … A borrowed dashboard could not be read

Console warnings:

Warning Meaning
gave up substituting variables after 10 passes A variable refers to itself
could not read the dashboard "…" A dashboard in decluttering_templates_from is missing or unreadable
<…> is already registered by something else, skipping it Another card owns that type — usually the original decluttering-card