How Home Assistant themes work

Themes are the cheapest change you can make to a Home Assistant install. One file, no custom cards, and the whole interface looks different. They are also the most commonly misunderstood. This guide covers what a theme actually does, why themes break, where they apply, and what to do when one will not show up. For which themes to put on, see our roundup of the best Home Assistant themes.

What a theme changes, and what it does not

A theme is a named set of CSS variable values. That is the whole of it. It sets colours, fonts, corner radius, shadows, and the large state-colour system that decides what an active light looks like versus an idle one.

What it cannot touch is anything structural. A theme will not change which cards appear, what order they sit in, how many columns a view has, or which layout that view uses. Those are properties of the view and of each card, not of the paint.

Layout lives in the dashboard rather than in the theme, and our guide to Home Assistant dashboards covers it. This matters because the most common disappointment with themes is installing three of them looking for a layout that no theme was ever going to deliver.

Why themes break

Home Assistant is rebuilding its frontend components, and each rebuilt component swaps its old CSS variables for a new set. A theme is just a list of variable values, so when a variable stops existing, the part of the interface that used it stops matching your theme and quietly falls back to the default.

Release 2026.5 was the sharpest example so far. Switches, checkboxes and text areas moved to the new component library, six switch variables were removed outright and replaced with a larger set, and every theme that had not been updated suddenly had toggles in the wrong colour. Before that, release 2025.8 introduced a semantic colour scale, and themes that only defined a primary colour found the new buttons ignoring them. Release 2026.7 changed no theme variables, which makes it the quiet one in a noisy run.

Home Assistant's own documentation is honest about this: it does its best to keep things working, but the behaviour of theme variables can change between releases. There is no versioned, supported theming interface, and a theme is not a plugin with a compatibility guarantee. It is a list of variables that the platform is free to rename.

How to install one

Whichever route you take, Home Assistant needs to be told to look for themes at all. That means a frontend block in configuration.yaml, with themes: !include_dir_merge_named themes indented beneath it. That points Home Assistant at a themes folder in your configuration directory.

Most people fill that folder through HACS. From there:

There is no theme editor

Worth stating plainly, because it catches people out: Home Assistant has no interface for creating or editing a theme. You can select one and you can reload the folder, and that is the extent of it. Themes are YAML, written by hand or forked from someone else's.

A couple of the bigger themes ship their own configuration helpers as separate downloads, and there are third-party generators around, but nothing built in. If you want to tweak a theme you have installed, you edit its file.

Where a theme applies

Three scopes, and they are not all in the place you would expect.

Per user. The profile page, reached by clicking your name at the bottom of the sidebar. This is the one almost everybody uses. It saves to your account, so it follows you to every device you sign in on, and every user on the same system can run something different.

Per view. A single view inside a dashboard can carry its own theme, set from the view editor. Useful for a wall panel view that wants to be darker than everything else.

The system default. This one is not a settings page. It is an action, frontend.set_theme, run from Tools, the panel called Developer tools before release 2026.8, or from an automation. A common pattern is an automation that runs it at startup so new users land on the right theme.

There is no per-device scope. Because the profile choice is tied to the account rather than the browser, the same user on a phone and on a wall tablet gets the same theme. Different themes on different screens means different Home Assistant users, which is the same conclusion the default dashboard leads to.

Dark mode

Home Assistant has a built-in dark mode, and it is separate from any theme you install. A theme can also define its own light and dark variants, using a modes block with light and dark beneath it. Variables layer in order: the default theme first, then the theme's own top-level values, then whichever mode is active.

If a theme defines only a dark variant, it is layered over the built-in dark theme. If it defines neither, you get its single look regardless of the toggle, because nothing will synthesise a dark version for you.

Theme, card-mod, or a custom card?

Three tools, and picking the wrong one is where the frustration comes from.

Use a theme when the change is a value applied everywhere. Colours, fonts, radius, shadows. Nothing to install beyond the theme itself, and it survives updates better than the other two.

Use card-mod when the change needs to target something specific: one card, or an element inside a card that no variable exposes. It reaches further than the other two and breaks more often, because it depends on internals that are free to change.

Use a custom card or a layout change when the change is structural. A different card type, different behaviour, a different arrangement.

One thing not to promise yourself: custom cards mostly follow your theme, because they read the same variables, but not universally. Several card families define their own variables internally, so a theme will not always reach them.

When the theme will not show up

The most common support question about themes is not about picking one, it is that the list is empty or the new theme is not in it. It is nearly always one of these.

The frontend block is missing from configuration.yaml, or the themes line under it is indented wrongly.

The frontend block appears twice in the configuration. Only one of them wins.

The theme file is not in the themes folder the include points at.

The theme is installed but themes have not been reloaded since. Run the reload action.

The theme was selected in a browser that has since had its storage cleared, or you have signed in as a different user. The setting lives on the account.