Be Smart, Go Local.

Home Assistant Decluttering Card Tutorial

Short tutorial for Decluttering Card in Home Assistant, used to cleanup your dashboard card configuration by reusing predefined templates.

The decluttering card for Home Assistants’ Lovelace Dashboard is a powerful tool used to clean up and minimize your card block configuration. When we design a dashboard, we tend to overuse the same card configuration for entities of the same type, eg. lights. This results in a huge block of code which can be tedious to go through when certain variables needs to be changed. This is where the decluttering card comes into play.

This card avoids repetition by allowing you to reuse the same configuration throughout your dashboard configuration and change only preset variables. The result is a nice, short and clean code which is easy to modify and change on the fly.

It was developed by RomRider, who is also the author of the highly customizable and versatile Button Card and advanced graphing ApexCharts Card.

Installation

HACS

The Decluttering Card is available in HACS (Home Assistant Community Store).

  • Open HACS
  • Click + Explore and Download Repositories
  • Under Frontend, search for Decluttering Card
  • Select the latest version
  • Click on Download
  • Click to Reload your resources

If you are using Lovelace in storage mode, add a resource reference:

resources:
  - url: /local/decluttering-card/decluttering-card.js
    type: module

Manual

  • Download decluterring-card.js from the Github Repo
  • Place the .js file in <config directory>/www/decluttering-card/decluttering-card.js
  • Add the resource reference
  • Restart Home Assistant

Usage

Decluttering Card works by defining templates to be dynamically reused in your Lovelace configuration. These need to be set under the decluttering_templates: object at the root of your dashboard configuration in Home Assistant. Each variable you want to subsequently change need to be enclosed in double square brackets and single quotes, ‘[[variable_name]]’. This will later be replaced with a real value in Lovelace. Optionally, you can define default values to variables by setting them under the default: object under decluterring_templates, eg ‘[[variable_name]]’: ‘[[variable_value]]’

Defining Templates

To define a decluttering template you intend to reuse, open your dashboard and click the three dots in top right corner and select Edit dashboard. Click the three dots again and select Raw Configuration Editor. Above everything else with no indentation, add your decluttering templates so the code look something like this:

decluttering_templates:
  my_template:
    card:
      type: entity
      entity: '[[entity]]'
      icon: '[[icon]]'
title: Home
views:
  - path: default_view
    title: Home
    cards:
.................

This example just shows where everything needs to be placed in your main lovelace-ui.yaml file. If you are using Lovelace in YAML mode, you can add the same code using your text editor (Studio Code Server, File Editor etc.).

Another good practice is to use !include and list all your templates in one decluttering_templates.yaml file and subsequently include that file as a dictionary in the main lovelace-ui.yaml file. This is good practice for reusing the same templates across any dashboard you want, without having to list them all in the main dashboard file. To do this, create a new file inside you config folder and name it decluttering_templates.yaml:

my_template_1:
  card:
    type: entity
    entity: '[[entity]]'
    icon: '[[icon]]'
my_template_2:
  card:
    type: entity
    entity: '[[entity]]'
    icon: '[[icon]]'
my_template_3:
  card:
    type: entity
    entity: '[[entity]]'
    icon: '[[icon]]'
......

Than you can !include this file to any dashboard you want to with a simple line of code (note: only works in YAML mode). Another advantage of this method is whenever you make a change in your templates, the change is reflected across all dashboards.

decluttering_templates: !include decluttering_templates.yaml

As an example, we can create a custom button-card and design it how we like it:

To convert the design to a template, we add it under the decluttering_templates object in lovelace-ui.yaml and change the value to a variable, in this case the icon and entity:

decluttering_templates:
  lights:
    card:
      type: custom:button-card
      color_type: icon
      show_last_changed: true
      show_state: true
      icon: '[[icon]]'
      entity: '[[entity]]'
      style: |
        ha-card {
          background-color: var(--primary-primary-color);
          box-shadow: none;
        }
      layout: name_state
      state:
        - value: 'off'
          styles:
            icon: null
            label:
              - font-size: 12px
              - font-weight: bold
            name:
              - text-transform: uppercase
              - color: var(--primary-color)
              - font-size: 16px
              - font-weight: bold
        - value: 'on'
          styles:
            icon:
              - margin: 0px
              - color: black
            card:
              - font-size: 14px
              - font-weight: bold
              - background-color: var(--primary-color)
            label:
              - font-size: 12px
              - font-weight: bold
            name:
              - text-transform: uppercase
              - font-size: 16px
              - font-weight: bold

The other card config changes a bunch of styling variables for the icon, card, label and name of the button-card which we intend to reuse. The background and border are also removed using card-mod.

Using the Card

To reuse this template in you dashboard, all we need is a simple short code defining the card type and variables:

type: custom:decluttering-card
template: lights
variables:
  - entity: light.living_room
  - icon: mdi:chandelier

In the end, 40 lines of code were converted to just 5! For visualization:

Summary

If you apply a little logic, you can cleanup your dashboard code significantly with the Decluttering card. You can define as many templates as you need, and as many variables per template as you want. For example, the custom button card is highly customizable and versatile, but because it has so many variables and options its code config per entity can stack up pretty substantially.

Please note, the custom button-card has its own templating system, which works similarly to the Decluttering card. I find this one to be cleaner, easier and more structured than the button-cards template defining system.

If you need help setting up the Decluttering Card, leave a comment bellow.

8 thoughts on “Home Assistant Decluttering Card Tutorial”

    • Hello,

      No, it’s not possible to use includes in Lovelace storage mode, only in YAML.
      You will have to list them all as a list under the decluterring_templates object.

      SHS

  1. Set up as described, but I get an error ” Cannot read properties of undefined (reading light) when calling my template. Any idea what would cause this?

    My template
    light:
    card:
    type: custom:mushroom-light-card
    entity: '[[entity]]'
    layout: default
    show_brightness_control: true
    show_color_temp_control: true
    use_light_color: true
    tap_action:
    action: toggle
    hold_action:
    action: more-info

    Calling the card
    cards:
    - type: custom:decluttering-card
    template: light
    variables:
    - entity: light.master_bedroom

    • Hello,

      You need to define decluttering_templates: before you actual template light:

      decluttering_templates:
      light:
      card:
      type: custom:mushroom-light-card
      entity: '[[entity]]'
      layout: default
      .....

    • Hi Joe,

      If you’ve successfully added the resource reference, you need to clear your cache by clicking CTRL + F5.
      If you are still having issues, test the page in incognito.

      Cheers

    • Well, you should first differentiate between Home Assistant Templates and Home Assistant Jinja Templating.

      The former is something you would use to predefine things, reuse through out Home Assistant and custom cards. Such as the decluttering card or button card templates.

      Templating is using the advanced Jinja2 templating engine to develop more complex code and conditions in some aspects of HA.

      See more here:
      https://www.home-assistant.io/docs/configuration/templating/

Comments are closed.