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; '*' means every dashboard (v1.8.0+). 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
views[].decluttering_defaults (v1.8.0+) mapping, or a list Values for the cards on one view. Beat the template’s own defaults (v1.9.0+); only a section’s values and a value on the card beat them
views[].sections[].decluttering_defaults (v1.10.0+) mapping, or a list Values for the cards in one section of a sections view. Beat the view’s; only a value on the card beats them 
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.
let (v1.7.0+) mapping, or a list — Values the template computes for itself from the others. A card cannot override one.
extends (v1.8.0+) string — Another template this one starts from. See Defining Templates.
category (v1.8.0+) string — Groups the template in the picker
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
let (v1.7.0+) mapping, or a list — Values the template computes for itself
extends (v1.8.0+) string — Another template this one starts from
category (v1.8.0+) string — Groups the template in the picker
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
devices (v1.8.0+) string, list or true Repeat over devices, by id or name pattern
floors (v1.8.0+) string, list or true Repeat over floors, by id or name pattern
labels (v1.8.0+) string, list or true Repeat over labels, by id or name pattern
group_by (v1.8.0+) string Fold an entity repeat into one copy per domain, area, floor or label
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 or list name, entity, id, area, domain, floor. none keeps the registry order; any other name is read as a key the copies carry (v1.3.0+), and attr:<name> reads a state attribute (v1.5.0+). A leading minus reverses one key, and a list breaks ties with the next (v1.5.0+)
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
offset (v1.5.0+) number Skip this many copies first, so two cards can split one list. total ignores the window
require (v1.5.0+) string or list Drop a copy whose named keys came out empty, before anything is counted
overrides (v1.5.0+) mapping Extra variables for particular copies, keyed by entity id, area id or pattern
with (v1.2.0+) mapping For an area source - or a device, floor or label one (v1.8.0+) - the entities to gather for each copy, 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
device_id, device, name, area, area_id, manufacturer, model (v1.8.0+) a device source The device and where it is
floor_id, floor, name, level (v1.8.0+) a floor source The floor
label_id, label, name (v1.8.0+) a label source The label
group, name, items, entities, entity_count (v1.8.0+) group_by The group and what fell into it
total (v1.2.0+) a registry source What matched before limit and offset, and after require (v1.5.0+)
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
pattern (v1.8.0+) string — A regular expression the value should match. Warns, never blocks
allowed (v1.8.0+) list — The values it may take. Warns, never blocks; wins over pattern
group (v1.8.0+) string — Folds the declaration into a section of the card editor

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|trim]] (v1.3.0+) Whitespace removed from both ends
[[name|capitalize]] (v1.3.0+) First character upper-cased, the rest left alone
[[name|replace:from:to]] (v1.4.0+) Every from swapped for to; no to deletes
[[name|prefix:text]] / [[name|suffix:text]] (v1.4.0+) Text put in front or after; an empty value stays empty
[[name|max:12]] (v1.4.0+) Shortened to that many characters, ending with …
[[name|map:a=1,b=2]] (v1.4.0+) Looked up in the pairs; *= catches the rest
[[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

The view strategy (v1.11.0+)

On a view, strategy: with type: custom:decluttering-card-plus. See Repeating Sections and Badges.

Key Type Description
type string custom:decluttering-card-plus
sections list Sections as written, and repeats that write one section per item
badges list Badges as written, and repeats that write one badge per item
variables list, or a mapping Values every repeated entry gets, underneath its own
decluttering_defaults mapping View-level values for the templated cards in the view
anything else   Passed to the view: max_columns, dense_section_placement, background…

A repeated entry:

Key Type Description
for_each list One copy per item
for_each_from mapping One copy per thing Home Assistant knows about. Same keys as below
section / badge mapping What each copy is, with placeholders filled from the copy
variables list, or a mapping Values every copy of this entry gets
empty mapping The section or badge to show when nothing matches

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

The same resource also registers the view strategy custom:decluttering-card-plus (v1.11.0+).

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