elax46/custom-brand-icons: a Home Assistant icon pack you can trim to the icons you use

Two prefixes, one set of drawings

The pack is a set of brand icons for Home Assistant, and the first thing to understand is that it uses two different prefixes depending on where the icon is being used.

Inside a Lovelace dashboard the icons are referenced with the prefix `phu:`, followed by the icon name, so an entity card would carry `icon: 'phu:eggs'` or `icon: 'phu:chicken'`. The Iconify framework is the other route: all icons are available there under the prefix `cbi`, and the icon set is browsable at the icon-sets listing for `cbi`.

The Iconify route is the more interesting one, because it means the pack is not locked inside Home Assistant. Anyone using the set through Iconify is reminded to comply with the licence, and for commercial purposes the project says you can contact the maintainer. That is worth pausing on, since the drawings are logos of real companies, and a logo carries trademark rights, and often copyright as well. A pack of brand icons is not a neutral asset, and the project is upfront that commercial use is a conversation to have rather than a free-for-all.

The pack itself covers the kind of thing Home Assistant users actually end up needing: the topics list names IKEA, Philips Hue and Xiaomi among the brands represented, and the icons are the sort of everyday product and food items that a generic icon set does not have.

Installing through HACS

The recommended route is the Home Assistant Community Store, and the README links to the HACS repository page for it.

After installing through HACS, you add the resource to your `configuration.yaml`:

frontend:
  extra_module_url:
    - /local/community/custom-brand-icons/custom-brand-icons.js

If you are using YAML mode, the same file is added as a resource in the Lovelace configuration, through the Raw Config editor under Configure UI or in `ui-lovelace.yaml`:

resources:
  - type: js
    url: /local/community/custom-brand-icons/custom-brand-icons.js

The `frontend` block and the `resources` list are two different mechanisms that do the same job, and the README treats the second as optional and specific to YAML mode users, which matches how Home Assistant itself is configured. The path in the first case points into the `community` directory, which is where HACS puts frontend modules.

The bundle is a JavaScript module loaded by the browser rather than a file that Home Assistant reads server side, so it is the frontend of the dashboard that is affected, and the entity names in your configuration are what the icons are attached to.

Manual installation into the www directory

The manual route is for people who do not use HACS, and it is five steps.

Download the `custom-brand-icons.js` file from the latest release, copy it into the `www` directory in your Home Assistant configuration folder, the directory where your `configuration.yaml` resides. Then add the frontend entry:

frontend:
  extra_module_url:
    - /local/custom-brand-icons.js

For YAML mode users, the resource entry goes in the Lovelace configuration as before:

resources:
  - type: js
    url: /local/custom-brand-icons.js

Finally, restart Home Assistant. That last step is not optional in the manual flow, because the resource is registered at startup, and the path changes between the two methods, from `/local/custom-brand-icons.js` in the manual case to the `community` path in the HACS case. Copying the wrong one is the most common mistake, and it produces a dashboard with no icons and no error message.

The file itself is tracked in the repository under `dist/`, and the README even carries a badge for its size in bytes, which is a useful signal when you are deciding whether to install the full pack or a trimmed one.

Generating a pack with only the icons you use

The most useful feature in the project is the icon viewer at elax46.github.io/custom-brand-icons, which serves two purposes. It shows the available icons, and it lets you generate a `custom-brand-icons.js` containing only the icons you want, so that you can streamline the pack and eliminate loading issues.

That is a real answer to a real problem. A dashboard frontend module is loaded by every browser that opens the dashboard, and a large icon set is dead weight if your house has forty devices. The trimmed build is the difference between a module that takes a noticeable moment to load and one that does not.

The README also links to the Iconify set for `cbi`, which serves a similar purpose from the other direction, since the Iconify route is a per icon reference rather than a whole pack loaded at once.

For a contributor, the request process is documented in the same section. A request is opened as an issue using the custom icon request template, and the rules are strict: provide an SVG file and a jpg logo, upload the files into the request so they are visible in the post, and include a name. Links to SVGs or images are ignored, and the README says outright that requests without uploaded files will be ignored and closed, on the grounds that the maintainer cannot spend time hunting for assets. People who have made their own icons are asked to open pull requests against the dev branch instead.

The build pipeline normalises and optimises the SVGs

The pack is generated, and the generation tooling lives in the repository rather than being hidden in the maintainer's machine. The `package.json` is a development manifest with a small set of dependencies that explain what the pipeline does.

`svgo` is the SVG optimiser, so each icon is reduced before it is bundled. `svgson` parses SVG into JSON, `svgpath` and `svg-path-bbox` handle path data and bounding boxes, and `fast-glob` finds the source files. Those four libraries together are the minimum needed to take a folder of SVGs and produce something uniform.

The scripts are named for the operations rather than the tools:

"scripts": {
  "normalize": "node script/normalize-icons.mjs",
  "clean": "node script/normalize-icons.mjs --clean",
  "vrt": "node script/normalize-icons.mjs --vrt",
  "clean:vrt": "node script/normalize-icons.mjs --clean --vrt"
}

The VRT variants relate to visual regression testing, running the normalisation in the mode that produces images for comparison.

The Docker Compose file ties the pipeline together and documents itself. Its comments say it performs two tasks, running the `custom-icons-builder.cjs` script to generate the custom icons, and building a local Docker image with node.js:22 and ImageMagick to normalise and clean up the generated files using `npm run clean:vrt`. The two commands to run it are `docker compose up build` and `docker compose up normalize --build`, and the working directory is mounted from the repository so the generated files land in the tree. The ImageMagick step is what makes the VRT comparison possible, since it renders the icons rather than only parsing them.

Cache problems after Home Assistant 2024.1.1

The last section of the user manual is a troubleshooting entry, and it is worth knowing about before you conclude the pack is broken.

Some addons, including official ones, have had cache issues since Home Assistant 2024.1.1, and the linked issue in the README is the discussion. The first workaround is to go to settings, then dashboard, then the three dots menu, click resources and add the resource pointing at the HACS path with a cache busting query string, of the form `/hacsfiles/custom-brand-icons/custom-brand-icons.js?hacstag=366862031202420`. A second resource is added as well.

That query string is the mechanism. Home Assistant caches frontend resources, and a resource whose URL never changes keeps serving the old file even after you install a newer release. Adding a changing parameter forces the browser to fetch it again.

For the shape of the project overall, the release numbering is dated, with tags like 2026.10.1 published on 2026-10-10, 2026.10.0 on 2026-10-02 and 2026.09.1 on 2026-09-28, and the last push to the repository was on 2026-10-18. The `icon-svg/` directory holds the source drawings, `dist/` the built bundle, and `hacs.json` and `info.md` are the metadata the HACS store reads. The licence is MIT for the pack itself, with the logo rights question handled separately through the Iconify terms.

Editorial conclusion

Adopt this pack if your Home Assistant dashboards show appliances and brands that the built-in icons do not cover, since that is exactly the gap it fills, and if you are willing to accept that icons are delivered as a JavaScript resource that Home Assistant loads as a module. Do not adopt it if you need icon files in a different shape, since the deliverable is a single bundle rather than a directory of assets, and do not expect commercial brand logos to be freely reusable, because the project itself points out that anyone using the set should comply with the licence and contact the maintainer for commercial use. Verify first that the icon you want is in the pack, either in the viewer or in the icon set listing, that the resource loads after a Home Assistant restart, and that you clear the browser cache if an icon does not appear, since cache issues have been reported since Home Assistant 2024.1.1.

Frequently asked questions

Official sources

1. elax46/custom-brand-icons on GitHub
2. License: MIT
3. Project website
4. README
5. Releases