Migrating from decluttering card
Your existing configuration keeps working. You do not have to change anything.
Decluttering Card Plus registers the original card's types as well as its own, so
custom:decluttering-card and custom:decluttering-template continue to work exactly as
before. The decluttering_templates key is unchanged.
- Install Decluttering Card Plus — see Installation.
-
Remove the original
decluttering-card(HACS → Decluttering Card → Remove, and delete its dashboard resource if you added it by hand). - Hard refresh the browser.
That is it. Your dashboards render as they did.
The same template, the same variables — one instance written custom:decluttering-card,
the other custom:decluttering-card-plus. This card serves both.
Because whichever card loads first claims the decluttering-card and
decluttering-template types, and Home Assistant loads resources in the order they were
added.
| Load order | What happens |
|---|---|
| Original first (usual case) | The original keeps serving your custom:decluttering-card cards. They work, but get none of the fixes or new features here until you remove it. |
| This card first | This card serves them instead. The original's bundle then logs a define error to the console when it finds the name taken. Nothing breaks. |
Either way there is no reason to run both, and the result depends on resource order rather than on anything you can see. Remove the original.
You can tell which is which from the browser console: this card announces itself as
DECLUTTERING-CARD-PLUS
Version …
and logs a warning if something else already owns a type:
decluttering-card-plus: <decluttering-card> is already registered by something else, skipping it.
Once the original is gone, use the -plus types for anything new:
| Old | New |
|---|---|
custom:decluttering-card |
custom:decluttering-card-plus |
custom:decluttering-template |
custom:decluttering-template-plus |
The -plus types are always available, whatever else is installed, so they are the safe
thing to write. There is no rush to rewrite existing cards — the aliases are supported, not
deprecated.
Everything below is new relative to the original card:
| Feature | Page |
|---|---|
| Template badges | Badges |
| Template rows and picture elements | Rows, Elements |
| Visual editors for templates and instances | Visual Editors |
visibility conditions inside templates |
Visibility |
| Share templates between dashboards | Sharing Templates Between Dashboards |
| CSS injection with variables | Styling |
| Defaults that reference other variables | Variables |
| Grid options passed through in sections views | Cards |
| Templates found inside sections views | Defining Templates |
Things that used to break and now do not:
- Values containing quotes, backslashes, newlines or tabs — previously produced
Bad control characterorUnexpected tokenfrom the JSON parser, which meant multi-line values and Jinja written as a YAML block scalar were unusable. - Values containing
$&or$1, which were treated as regular-expression replacement patterns instead of literal text. - Variable names containing regex characters.
- Mappings and lists used inside a longer string.
- Defaults referring to other variables, in any declaration order.
- Self-referencing variables, which now stop with a console warning instead of looping.
- A card that hides itself by any means now collapses the wrapper. Previously only an
inline style was detected, so a card hidden by a stylesheet rule or the
hiddenattribute left an empty gap. - Cards report their grid options to the sections layout, so templated cards are no longer laid out at the default size.
Mixing types is fine. A custom:decluttering-card may use a template defined by a
custom:decluttering-template-plus card, and vice versa. They are the same implementation.
decluttering_templates is unchanged, including template cards placed in views.
The -plus template card is found in sections views too, which the original did not
look in.