Building a Home Assistant Dashboard From Zero

Most Home Assistant dashboard guides show you a finished dashboard. That is the least useful picture, because the interesting part is what happens between an empty view and that screenshot, and it is where people give up.

So I built one in five steps and kept every step as its own file. Same instance, same data, same screen size, nothing else changed between the images. What follows is those five states in order.

Step one: the empty view

A new dashboard is a headline and a lot of nothing. No guide shows this, and it is worth seeing once, because the panic of not knowing where to start is a real reason dashboards stay bad.

Step one: nothing at all.

Step two: the first card

One tile. It occupies a single column and leaves the rest of the width empty, which looks broken and is not — the grid only fills out once there are enough cards to fill it.

Step two: one card, and a lot of empty grid.

Step three: five cards, no order

This works. Every value is on screen, everything is readable, and you could stop here. Most dashboards do stop here, and it is why so many of them look like a list of numbers rather than something you glance at.

Step three: five cards. Everything readable, nothing organised.

Step four: the same cards, grouped

Thirteen cards now, in three groups with headings. This is the step the whole post exists for. Between the third image and the fourth, no new content is added. The same values are on screen. What changed is that they are grouped and labelled, and the difference in how quickly you can read it is larger than anything I did later.

Step four: the same values, in three labelled groups. Compare this with the image above.

If you take one thing from this: the fix for a dashboard that feels cluttered is almost never another card. It is putting the cards you have into sections that say what they are.

Step five: the finished view

Twenty-three cards, with gauges, a twelve-hour history graph and the setpoints that are actually adjusted. This is the version I kept, and it is only two steps of work past the one that looked like a list.

Step five: 23 cards, gauges and a history graph.

What step four looks like as configuration

The grouping is a view of type sections, and each group is a grid with a heading card as its first entry. Two settings do most of the work: max_columns caps how wide the whole view spreads on a large screen, and column_span lets one section take more width than its neighbours.

views:
  - title: Übersicht
    type: sections
    max_columns: 3
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: heading
            heading: Energie
            heading_style: title
            icon: mdi:solar-power-variant
          - type: gauge
            entity: sensor.pv_leistung
            name: Erzeugung
            min: 0
            max: 8000
            needle: true

On a 27-inch screen a view without max_columns spreads to five or six columns and stops being readable at a glance, which was not obvious to me until I looked at it on a monitor rather than a laptop. Three is the number I kept.

Three things that broke on the way

Markdown cards used as headings wrecked the layout. They count as a grid cell, so the tiles below them redistributed into the wrong columns and the whole section looked misaligned. The native heading card spans the full section width instead and fixes it.

Numbers jumped every time they changed. Proportional digits have different widths, so a value ticking from 1.111 to 1.222 shifts the whole line. Switching the number font to one with tabular figures stops it. You cannot see this in a screenshot, and you cannot unsee it once the dashboard is running.

A battery ring rendered as a full disc. I built it as a conic gradient with a hole in the middle whose background was set to a Home Assistant CSS variable. That variable does not resolve inside the shadow DOM of the card I used, so the hole stayed transparent and the gradient showed through. The fix was to stop cutting a hole in a disc and draw a circle with a dashed stroke instead. The card in question is button-card, which is not part of Home Assistant — it comes from HACS, and installing that first is the step people skip before wondering why a template does nothing.

Why the files, not the editor

Everything above is a YAML dashboard, wired in through the configuration rather than clicked together in the interface. The reason is not purity. A dashboard defined by a file has a state you can reproduce: five files gave me five identical framings for the five images, and doing that by hand across five screenshots would not have held.

The editor is faster for a first draft. The file is what lets you keep versions of a layout and go back to one. If you want the finished thing rather than the walk-through, I put two dashboards built from stock cards in a separate post, and the card directory lists what is available once you go past the built-in ones.