lovelace-ios-themes: iOS styled Home Assistant dashboards, in 28 variants

The problem: a dashboard that does not look like the rest of your phone

Home Assistant's Lovelace dashboard is capable and, by default, plain. People who use their phone all day and their home dashboard on a wall tablet often want the two to look like the same product, and the request that comes up most often in the community forum is for an iOS look.

This project is that request, packaged. It is a set of Lovelace themes inspired by iOS Dark and Light Mode, with different backgrounds, and it is installed the standard way for Home Assistant customisation: as a HACS default integration.

The lineage is worth stating, because theme work is derivative by nature. The theme is by basnijholt and is modified from a Gist by kalkih, and the project describes itself as a generalized version of the iOS Dark Mode Theme that came before it. Generalising a single hand-written theme into a matrix of modes and backgrounds, and then into something installable and generated, is the actual contribution here.

The audience is Home Assistant users who care about appearance and are willing to accept a community theme, and the size of the install is modest: the themes are YAML files with a Jinja2 template behind them, not a plugin that hooks into anything.

The licence is MIT, the default branch is master, the last push was on 2026-07-21, and the published releases are v3.0.3 and v3.0.2 from 2026-05-11 and v3.0.1 from 2024-09-09.

Twenty-eight themes, and how the naming works

The documentation is precise about what the install contains: installing this theme adds 28 different themes, and it includes both Dark and Light Mode and 7 different HomeKit backgrounds.

The naming scheme carries both axes, so a theme name tells you the mode and the palette. The list runs from ios-light-mode-dark-green and ios-dark-mode-dark-green through the light blue, light green, orange, blue-red, red and dark blue pairs, and then the same set again with the -alternative suffix.

That suffix is the important part of the naming, because it selects a different set of assets rather than a different colour scheme. The alternative versions use locally hosted background images instead of the remote ones, and the two are otherwise the same theme.

The backgrounds themselves are HomeKit wallpapers, which is the visual reference that makes the set coherent rather than a collection of unrelated wallpapers. Seven of them, in two modes, gives the twenty-eight combinations without any of them being a different design in any meaningful sense.

The project also publishes screenshots from the author's own Home Assistant instance, and the configuration files for that instance are in a separate repository, which is the more useful artefact for anyone who wants to see the themes in a real dashboard rather than on a blank page.

The 3.0.0 change: remote backgrounds by default

The most consequential decision in the project is one that sounds trivial, and it is about how the background image gets to your browser.

As of version 3.0.0, the project introduced an alternative to Base64-encoded background images to boost performance. Before that, embedding a large wallpaper directly in the theme YAML meant every dashboard load carried the image as text inside the configuration, which is slow to parse and heavy on the browser.

The default now is remote background images hosted on GitHub, which the documentation explains is for faster caching and loading times. The alternative versions, marked with the -alternative suffix, use locally hosted background images, and they exist for users who prefer to host images locally on their Home Assistant setup, or who are in environments with poor internet connectivity.

That is a sensible split, and it is also a trade. The default is faster in the common case and requires no configuration beyond the installation steps, at the cost of a dependency on a third party repository being reachable and on a request to GitHub for the image. The alternative is fully self-contained, at the cost of the user downloading and storing every wallpaper they want.

The choice is also not reversible per dashboard without a theme change, because the two variants are separate entries in the theme list. Users on a flaky connection or a private network will want to think about that before they install.

Setting up locally hosted backgrounds

The local route is documented as a step-by-step process, and the first step is to create the directory Home Assistant will serve from:

mkdir -p /config/www/ios-themes

Home Assistant automatically serves files from the www folder under /local/, which is why the images go there and why the theme paths for locally hosted images are referenced as /local/ios-themes/.

The second step is to download the wallpapers with wget, one command per background. The documentation gives the full set, and this is the pattern they all follow:

wget -O /config/www/ios-themes/homekit-bg-dark-blue.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-dark-blue.jpg

The list covers the dark blue, light blue, dark green, light green, orange, blue-red and red backgrounds, and the documentation notes to repeat the command for all the backgrounds you need, making sure to replace the file name with the appropriate background name from the themes you are using.

The third step is to select the alternative version in your Home Assistant profile settings, for example ios-dark-mode-dark-blue-alternative, and then reload your Home Assistant theme settings or restart Home Assistant.

One detail in the example commands is worth noting rather than copying blindly. The light blue example in the step-by-step section writes to the same dark blue file name, so a user who follows it literally ends up with a wrong image under the right name. The command summary further down the page has the correct destinations. Read the summary rather than the narrative example.

How the themes are built: a template, a script and a linter

The repository layout explains the generation approach. There is a template.jinja2 file, a create-themes.py script, a settings-light-dark.yaml file, and a themes/ directory holding the generated output, plus a docs/ directory and hacs.json for the store metadata.

The primary language of the project is listed as Jinja, which is the giveaway: the twenty-eight theme files are not written by hand, they are rendered from one template with the mode and the background as parameters, and settings-light-dark.yaml holds the values that vary between them.

The tooling requirements confirm the shape of the project. The requirements file pins Jinja2, pillow for image handling, pre-commit, PyYAML and yamllint, and the repository has a .yamllint configuration and a .pre-commit-config.yaml, with a CI badge for the yamllint action. So the generated YAML that Home Assistant consumes is linted in continuous integration, which matters more than usual for a file that is machine written and installed by a lot of people.

The pillow dependency and the fact that the backgrounds are pulled from a themes/ directory in the same repository explain how the image files travel with the theme, and the wget commands in the documentation point at that directory on the master branch.

Licence, maintenance and what the project does not do

Two things to check before you put this on a dashboard you care about.

The first is the licence, and it is split. The project itself is MIT, which is what covers the theme files, the template and the scripts. The assets, the HomeKit wallpapers, are not covered by that, and the licence record in the repository is the custom one that GitHub cannot classify, with a separate file in the assets area. The published terms include a Creative Commons Attribution-NonCommercial-ShareAlike condition, so if you are running a commercial service, or monetising a dashboard, that clause is the thing to read first. This is not legal advice, it is the reason to look at the file rather than assume the MIT badge covers everything.

The second is where the images come from. The default themes fetch them from a GitHub repository, which means a dashboard with the default themes makes a request to a third party, and it means the themes break if that repository or the raw content host is unreachable, which is also why the alternative variants exist.

On maintenance, the repository is not archived and the last push was on 2026-07-21, with the v3.0.3 and v3.0.2 releases from 2026-05-11 and v3.0.1 from 2024-09-09, so the project is moving but slowly, and the 3.0 series has been stable for a while.

What the project does not do is worth stating plainly. It is a set of themes, not a component. It does not add cards, it does not change Lovelace's behaviour, and it does not give you the iOS widgets, the status bar or the app layout, only the colours, the typography and the wallpaper. If what you want is a Home Assistant that looks like the iOS Home app, the honest answer is that this is the visual half of that project and the rest has to be your own work.

Editorial conclusion

Adopt lovelace-ios-themes if you run Home Assistant and want your dashboard to look like iOS without writing a theme by hand, and if you are comfortable with a community theme that pulls its background images from a GitHub repository. Do not adopt it if your Home Assistant instance is air-gapped, without using the alternative variants and hosting the images yourself. Before you install, decide which mode you want, because the default and the alternative variants are separate entries in the theme list, and read the licence terms, since the assets carry a Creative Commons Attribution-NonCommercial-ShareAlike condition while the code is MIT.

Frequently asked questions

Official sources

1. basnijholt/lovelace-ios-themes on GitHub
2. Issues
3. License: MIT
4. README
5. Releases