⚠️ Beta: icon data is now loaded on demand
This is a pre-release for testing. It changes how the icon pack is built and delivered, so please read the notes below before updating.
What changed
Until now, custom-brand-icons.js contained every icon in a single file (~4.5 MiB parsed, ~1.6 MB gzipped), and Home Assistant fetched and parsed it on every dashboard load, whether or not the dashboard used a phu: icon.
The pack is now split in two parts:
custom-brand-icons.js: a small entry file (~33 KB) with a name → chunk manifest.cbi-*.js: 33 chunks of at most 145 KiB each, loaded only when an icon they contain is first used.
Expected impact
Measured with gzip -6 against a single-file build of the same 1,785 icons:
| Icons used on the page | Transferred (gzip) | vs. before |
|---|---|---|
| none | ~10.7 KB | 0.6% |
| 5 | ~260 KB | 15.5% |
| 20 | ~786 KB | 47% |
| 80 | ~1.47 MB | 88% |
| all | ~1.70 MB | 101.5% |
Dashboards using a handful of icons download a fraction of the set. Pages using hundreds of icons transfer slightly more than before, across more requests.
Compatibility
- HACS users: no action needed. Make sure you update through HACS so that all release files are downloaded.
- Manual installs (breaking change): you must now download all the files attached to this release (
custom-brand-icons.jsplus everycbi-*.js) and keep them together in<config>/www/custom-brand-icons/. The resource URL becomes/local/custom-brand-icons/custom-brand-icons.js. Replacing only the entry file will leave you with no icons.
Other changes
- Release and build workflows now attach the chunks and run
verify-dist, which checks every icon in the built pack against its SVG source before publishing. - A missing chunk only blanks the icons it contains, not the whole pack, and a retry requests a fresh URL.
How to test
- In HACS, open Custom Brand Icons → Redownload → enable Show beta versions → pick this version.
- Restart Home Assistant and hard-refresh your browser (clear the cache).
- Check that your dashboards render their
phu:icons and that the icon picker lists and previews them correctly.
Feedback wanted
Please report in the issue tracker (referencing #1674):
- icons that fail to load or appear blank;
- HACS install/update problems, especially upgrading from the single-file version;
- before/after numbers (requests, transferred size, load time) from your own setup.