Themes and appearance

Why this matters

After the first 12 chapters, your devices have names, your areas are organized by floor, your dashboards have views, and your automations run on their own. Yet the interface may still look exactly as it did on day one.

Appearance has a direct effect on usability. If the interface is unpleasant or hard to read, people stop opening it and return to physical switches. When it suits your home's lighting, remains readable on your devices, and feels comfortable at night, everyone is more likely to keep using it.

This chapter addresses three specific problems:

• Glare at night: A bright white interface can feel like a flash in a dark room. Automatic dark mode solves that problem.
• Different preferences: One person may prefer a dark, high-contrast display, while another finds it difficult to read. Each user can choose a separate theme.
• An unfinished-looking wall display: The default colors and “Home Assistant” browser title can make a permanently mounted tablet look more like a test system than a finished control panel.

Community-theme steps require HACS; install it as described in Appendix A. See Chapter 6 for dashboard editing.

What exactly is a theme?

A Home Assistant theme does not redraw the interface. It supplies a set of visual values, primarily through CSS variables.

Imagine a row of labels on a wall:

• “Primary color = sky blue”
• “Card background = white”
• “Primary text = dark gray”

Interface components read these shared values instead of choosing their own colors. Change a value, and buttons, cards, and sidebars throughout the interface update together. That is why a theme file containing only a few dozen lines can transform the whole system.

This mechanism also limits what a theme can do:

First, distinguish between three concepts that are often confused:

Changing a theme does not change your cards, and editing cards does not change the theme. The two are independent.

Where to find theme settings

Home Assistant 2026.2 changed both the location and behavior of this setting.

Current location: Profile. Select your name at the bottom of the sidebar. On the General tab, find the Theme selector under User preferences; Home Assistant describes it as “What does Home Assistant look like?”

The Home Assistant 2026.2 release notes state: "The theme has been moved! You can now find and switch your favorite appearance directly in your user profile, so that you can apply the same theme on any device you log in to."

The theme section in Profile usually contains two settings:

1. Choose a theme

   The menu always includes “Default,” along with any community themes you install later. A new system has only the default theme; this is expected.

2. Choose light and dark mode

   If a theme provides both light and dark modes, you can choose either one or let Home Assistant follow your phone or computer. When the operating system switches to dark mode, Home Assistant follows it. Select a fixed mode only if you do not want automatic switching.

   The option's name and position vary by version—some releases show “Auto,” while others provide Light and Dark buttons. Follow the labels shown in your version and look for the option that follows the system setting.

The same release also moved Developer Tools from the sidebar into Settings. In 2026.8, “Developer tools” was shortened to “Tools.” This chapter therefore uses the current path, Settings → Tools. On an older release, use Developer Tools in the sidebar; the available functions are the same.

Choose a monitoring or control-oriented style

Choose a design goal before installing themes. Most shared dashboards favor either dense monitoring or simple controls.

A useful rule is: monitoring screens can be information-dense; control screens should be simple. A personal energy view may contain many charts, while a shared entryway tablet should present only a few large, clear controls.

These approaches can coexist. The section on assigning a theme to an individual view explains how.

Built-in themes vs. HACS community themes

Home Assistant includes the Default theme with light and dark modes. Version 2026.2 redesigned it, replacing the old blue top bar with styling aligned with Settings. A visual change after upgrading is therefore expected.

If you want more choices, there are three ways:

When choosing a community theme, apply the same criteria used for integrations in Chapter 11. Start with the date of the latest update. A theme untouched for two years may still use variables that Home Assistant has removed, leaving parts of the interface unstyled.

Install your first community theme

The process has five steps. Do not skip steps 2 and 3; otherwise HACS may report success while the theme remains absent from Profile.

1. Download a theme in HACS

   Open HACS, search for the theme you want, open its page, and select Download. The HACS documentation states that themes downloaded through HACS are stored in the themes/ directory inside your Home Assistant configuration directory—commonly referred to as /config/themes/.

   The HACS category is named “Theme.” If it does not appear in your installation, theme support may not yet be enabled; complete the next step first.

   

2. Add three lines to configuration.yaml

   Use an add-on such as File editor or Studio Code Server to open configuration.yaml in the configuration directory. Add this at the top level:

   frontend:
     themes: !include_dir_merge_named themes

   These lines merge files from themes/ into the theme mapping. !include_dir_merge_named is a Home Assistant YAML extension. The frontend documentation also allows another directory, such as !include_dir_merge_named my_themes, but HACS uses themes.

   If configuration.yaml already contains frontend:, do not add another one. Add themes: under the existing key. YAML does not allow duplicate keys at the same level.

3. Validate the configuration

   Go to Settings → Tools → YAML, select Check configuration. Correct every reported error before proceeding; indentation and extra colons are common causes.

   Danger: A YAML syntax error can prevent Home Assistant from starting. Always check the configuration before restarting. If startup fails, correct the file through available host access or restore a known-good backup as described in Chapter 9.

4. Reload themes

   After adding the frontend: block for the first time, restart Home Assistant. Later theme edits or installations do not require a restart. Open Settings → Tools → Actions and run frontend.reload_themes. It takes no parameters; in YAML mode, enter this single line:

   action: frontend.reload_themes

   This action reloads the theme settings from configuration.yaml without restarting Home Assistant. If the selected theme no longer exists after the reload, Home Assistant returns to the standard theme. Only administrators can run this action.

   Settings → Tools → YAML can also reload configuration. Quick reload reloads all supported configuration, while this tab may provide controls for reloading individual items. If Themes is not listed, run the action above.

   

5. Apply the theme in Profile

   Select your name at the bottom of the sidebar, then find the theme selector on the General tab. The newly installed theme should now appear in the menu. Select it, and the interface should change immediately without a refresh or another login.

   If it does not change, try a hard refresh first (Ctrl + Shift + R). The browser cache is the most common cause.

Create a theme: YAML structure and variables

Once you understand the structure of a theme file, you can fine-tune an existing theme or create one from scratch. The minimum example in the Home Assistant frontend documentation looks like this:

frontend:
  themes:
    happy:
      primary-color: pink
      accent-color: orange
    sad:
      primary-color: steelblue
      accent-color: darkred

If you use the !include_dir_merge_named themes approach shown above, create a new file in /config/themes/, such as my_home.yaml. Do not repeat frontend: or themes: inside that file; start directly with the theme name:

my_home:
  primary-color: "#2f8f6b"
  accent-color: "#e0a458"
  primary-text-color: "#1c1c1c"
  card-background-color: "#ffffff"
  primary-background-color: "#f4f2ed"

Colors can use a named value such as pink, hexadecimal such as "#2f8f6b", or rgb(47,143,107). Quote values that begin with #; otherwise YAML treats the remainder as a comment.

Light and dark modes

A practical theme provides both modes. In Home Assistant, add a modes: block:

day_and_night:
  primary-color: coral
  modes:
    light:
      secondary-text-color: olive
    dark:
      secondary-text-color: slategray

The order in which Home Assistant applies these values is worth remembering because it explains why a change may appear to have no effect:

1. Start with the default theme

   Home Assistant first loads all variables from the default theme. Variables that you do not define therefore retain their default values rather than becoming transparent or black.

2. Apply mode-independent values

   Next, Home Assistant applies variables defined at the theme's top level, outside modes:. In the example above, primary-color: coral applies in both light and dark mode.

3. Apply mode-specific values last

   Values under modes: light: or modes: dark: have the highest priority. If a variable appears at both the top level and under a mode, the mode-specific value wins.

The documentation describes two additional behaviors: a legacy theme with no modes: block uses the default light theme as its base; if a theme defines only a dark mode, Home Assistant selects that mode automatically.

Common theme variables

In theme YAML, write the variable name without two leading hyphens. In card-mod or CSS, reference it as var(--primary-color). The most useful variables are listed below:

Why the color of an active light is more complicated than it seems

Entity icon colors often cause confusion because no single variable always takes precedence. The Home Assistant frontend documentation defines the following lookup order: the more specific the variable, the higher its priority. Home Assistant uses the first matching variable and ignores the rest.

To use warm orange for active lights and blue for active climate entities, set state-light-active-color and state-climate-active-color. To change the fallback for every active entity, set state-active-color.

Apply themes to views and system defaults

Assign a theme to a single view

This is how a dense control-room view and a spacious family view can coexist. Each dashboard view can specify its own theme. The Home Assistant view documentation defines theme as an optional string that applies a theme to the view and its cards.

Enter dashboard edit mode, select the pencil icon for the view you want to change, find the Theme field, and choose a theme. To configure it directly in YAML, use the documented format:

- title: Home
  theme: happy

For example, keep the main family dashboard simple and spacious, then create a dark, information-dense “System” view for CPU, network, battery, and Zigbee signal data. Each view retains its own appearance.

Use an automation to change the system-wide default theme

You can change the system-wide default themes with an action—for example, to provide everyone with a light theme during the day and a dark theme at night. The action is frontend.set_theme; the Home Assistant documentation gives this example:

action: frontend.set_theme
data:
  name: "HA Light"
  name_dark: "HA Dark"

The name parameter sets the light-mode theme; use "default" to return to the standard theme. The name_dark parameter sets the dark-mode theme; use "none" to remove that override. You must provide at least one parameter. Home Assistant saves the setting across restarts, and only administrators can run the action.

Using the three-part automation structure from Chapter 8, you can switch themes at sunset like this:

alias: Switch to dark theme at sunset
triggers:
  - trigger: sun
    event: sunset
actions:
  - action: frontend.set_theme
    data:
      name: "my_home_dark"

card-mod: styling beyond themes

Themes can change only the variables that Home Assistant exposes. Tasks such as enlarging the title on one card, rotating one button's icon by 45 degrees, or making a card turn red above 28 degrees are beyond a theme's scope. For those changes, use card-mod.

card-mod is a frontend custom component available through HACS. It inserts CSS styles into dashboard cards. The project is actively maintained and provides a compatibility table. Installing an incompatible version is a common reason that correctly written styles have no effect. Check your Home Assistant version first:

HACS installs the latest release by default. If your Home Assistant installation is older, manually select the compatible card-mod version in the HACS download dialog.

To use card-mod, add a card_mod: block to the card's YAML configuration:

type: entity
entity: sensor.living_room_temperature
card_mod:
  style: |
    ha-card {
      color: red;
    }

ha-card is the card's outermost element, and the declaration inside braces is standard CSS. To use theme colors instead of hard-coded values, reference a variable:

card_mod:
  style: |
    ha-card {
      border: 1px solid var(--primary-color);
      border-radius: 18px;
    }

Rebranding: change the “Home Assistant” name

For a wall-mounted tablet or a shared office display, you may want the browser title, icon, and home-screen name to use your household or organization's identity. Start with this important limitation:

The practical options are:

extra_module_url is documented by the Home Assistant frontend integration. Configure it like this:

frontend:
  extra_module_url:
    - /local/my_module.js

/local/ maps to the www/ directory inside the Home Assistant configuration directory. Home Assistant loads the module using import(). The loading mechanism is supported, but you are responsible for the code you load.

The name of the progressive web app (PWA) added to a home screen comes from a manifest file supplied by the server, and Home Assistant does not expose a setting for it. The simplest solution is to edit the name when selecting Add to Home Screen on your phone. This changes only the shortcut and carries no Home Assistant upgrade risk.

Interface language, fonts, and non-Latin text

Switch interface language

There are two levels of language that many people confuse:

In addition to language, Profile localization settings control the time zone, number format, time format, date format, and first day of the week. These preferences are tied to your account and follow you to every device where you sign in. Family members can therefore choose different formats—for example, a 12-hour clock—without affecting one another. System-level locale settings, including the time zone, units, currency, country, and language, are covered in Chapter 2.

Community volunteers translate Home Assistant through Lokalise, and each release includes the latest available translations. Traditional Chinese has long been supported and appears by name in the language menu. Because translation is volunteer-led, new features may remain partly in English for their first few months. This is normal and translations usually arrive within the next one or two releases.

Practical issues with Chinese fonts and layout

Home Assistant does not bundle a Chinese font; it asks the browser to use a system font instead. The same dashboard can therefore look different across platforms:

• iPhone / iPad / Mac: Chinese text usually appears in PingFang and needs little adjustment.
• Android: A font from the Noto Sans CJK family is common and usually works well.
• Windows: Chinese text often falls back to Microsoft JhengHei, whose lighter weights can look blurred on dark backgrounds.
• Low-cost China-market tablets: These are the most likely to have limited font packages. A device may include only Simplified Chinese fonts, leaving some Traditional Chinese characters missing or displayed as boxes.

Three practical measures help:

1. Keep names concise

   Chinese characters take up more horizontal space than Latin letters, so long entity names are easily truncated on phone cards. Four to six Chinese characters is the safest length. The naming principles in Chapter 4 directly affect the finished interface.

2. Font weight matters more than typeface

   Thin text can look blurred on a dark background. For a dark theme, increasing text contrast is usually more effective than changing the typeface: changing the typeface requires a third-party module, while changing the color requires only one theme variable.

3. Test the wall display in place

   Do not stop after adjusting the theme on a computer. Check the wall tablet from the distance at which people normally use it. Text and controls that look adequate at a desk may be too small in their actual setting.

Dark-mode contrast and accessibility

The most serious failure of a dark theme is not its appearance but its readability. The designer may see it clearly in a bright room on a high-end display, while an older family member cannot. Test it on different displays, in different lighting, at typical viewing distances, and with different users.

Follow these practical rules:

Also consider two physical conditions that cannot be solved by theme settings alone:

• Outdoor and entryway use: In bright sunlight, light themes can be easier to read than dark themes. If you regularly use Home Assistant outdoors, leave the mode on Auto rather than locking it to Dark.
• Night-time use: Darkness is only part of the requirement; low brightness matters too. The device's dark mode and automatic brightness handle much of this, provided the theme does not use large white card backgrounds.

Common problems

1. HACS reports that the theme is installed, but it is missing from the Profile menu

   In about 90% of cases, configuration.yaml does not include frontend: themes: !include_dir_merge_named themes, or Home Assistant has not been restarted since the setting was added. Adding the frontend: block for the first time requires a full restart. After that, frontend.reload_themes is sufficient.

   In the remaining cases, the directory name or location does not match the configuration. Confirm that the configured themes path matches the themes/ directory at the HACS location and directly contains at least one .yaml file.

2. The configuration check reports a YAML error

   Check four items: indentation uses spaces rather than tabs; a space follows each mapping colon; colors beginning with # are quoted; and only one frontend: key exists at that level. A duplicate key can produce an error reported on another line.

3. Selecting a theme has no effect, or the entire screen turns black

   Start with a hard refresh (Ctrl + Shift + R), then try a private browsing window. If the problem remains, switch back to Default. If the interface returns to normal, the theme is incompatible with your Home Assistant version.

   Frontend regressions can also prevent a theme from applying and are often corrected in a later minor release. If the problem began after an upgrade, read that release's notes and known issues before rewriting the theme.

4. I changed a variable, but part of the interface remains unchanged

   There are three common explanations: the component does not use that variable (inspect it in the browser to identify the actual variable); a value at the theme's top level is overridden by the same variable inside modes:; or the variable was renamed or removed in a newer release. The Home Assistant variable list is marked as a work in progress, so it is not exhaustive.

5. I want a dark theme on my phone and a light theme on my computer

   Since 2026.2, the selected theme is tied to the account and remains consistent across that account's devices. The Home Assistant project currently has no plan to restore per-device theme selection. The available workaround is to create a separate user account for the device.

6. My frontend.set_theme automation has no visible effect

   A theme selected in Profile takes priority over the system default. Set the Profile theme back to Default so the automation can affect your account.

7. card-mod styles broke after an upgrade

   First confirm that the card-mod version supports your Home Assistant version; the project page provides a compatibility table. Update it through HACS if necessary. If the versions match but the style is still broken, Home Assistant's internal component structure has probably changed and the selector must be updated. This maintenance burden is an inherent cost of card-mod.

8. I can't find Developer Tools

   Version 2026.2 moved it from the sidebar into Settings, and version 2026.8 shortened its name to Tools. The current path is Settings → Tools. The YAML, States, Actions, and Templates tabs remain available there.

FAQ