Add Custom Brand Icons To Home Assistant: 5-Step Easy Setup Checklist

add custom brand icons to home assistant — a practical checklist to upload, register, assign, verify, and rollback custom brand icons so your Lovelace dashboard and automations show the right brand glyphs.

• Prerequisites: what you need before touching icons (save time and avoid pitfalls)
• Shortest realistic path: zero-code reality check and a 10-minute UI-friendly method
• Step-by-step: Add a single custom icon (UI-first checklist for beginners)
• Full library install: file naming, folder structure, and Lovelace resource mapping (scale safely)
• Icon image specs & performance numbers you must follow
• Troubleshooting checklist: fast diagnostics and fixes for common failure modes
• Verification, rollback & automation use-cases (confirm, undo, and automate)
• Conclusion
• FAQ

Prerequisites: what you need before touching icons (save time and avoid pitfalls)

Before you start, confirm these environment items so you don’t waste time chasing path or permission errors.

• Home Assistant core: Any recent HA install with Lovelace UI works. Note: the brands-proxy API was added in Home Assistant 2026.3 — see Developers blog (1) for version notes (1 fact: “brands-proxy API added in Home Assistant 2026.3”) — developers.home-assistant.io (2026-02-24).
• Filesystem: create and verify write permissions on /config/www/community/custom-brand-icons/. Manual installs place the JS or SVGs here — the repo and docs expect this path (GitHub repo, 2026-04-20).
• Optional: HACS (Frontend) — strongly recommended for easiest installs, updates and rollback (see the HACS install flow in the Step-by-step section below).
• Resource registration: you’ll add a Lovelace resource either via UI (Settings > Dashboards > Resources) or in YAML under resources: / frontend.extra_module_url — both work; UI is simpler for beginners (GitHub, 2026-04-20).
• UI vs YAML mode: UI method is preferred for resource registration. If comfortable editing YAML, you can add a resources entry; otherwise use the UI path above.

Pitfall to avoid: Do not assume the mobile app will immediately reflect new icons — mobile apps cache frontend assets aggressively. Always restart HA and force-refresh the mobile app when verifying.

Internal resources to help: Home Assistant basics — Dashboard and Lovelace overview, Build LCARS Home Assistant Dashboard, and Home Assistant Raspberry Pi cover file access and Lovelace basics.

Shortest realistic path: zero-code reality check and a 10-minute UI-friendly method

Reality check: there is no reliable zero-code, UI-only way to add a single custom brand icon across all Home Assistant installs — you’ll need either HACS or to add a JS resource in /config/www. Research Findings: “No reliable data found for a pure zero-code UI-only single icon upload” (Research Findings, 2026-04-20).

Fastest practical UI-friendly method (under 10–15 minutes in many cases): install the Custom Brand Icons package via HACS (Frontend) or manually upload custom-brand-icons.js to /config/www/community/custom-brand-icons/ and register the resource in the UI — no YAML required.

• Why not pure UI? Home Assistant’s UI does not offer a single-file icon uploader that auto-registers a JS icon pack and maps prefixes; the JS resource or HACS provides mapping and the phu: prefix used by icon pickers.
• Time: expect under 10 minutes for HACS installs on responsive systems; allow extra time for restarts, cache clears, or slower hardware (Pi vs NUC).
• Research note: No reliable zero-code UI-only option found — if you want to test further, try uploading one SVG + adding resources in a clean test install and measure time-to-display in browser and mobile (see “What to test next” below).

What to test next: measure dashboard load before/after adding 50 icons on your host (Pi4 vs NUC) using browser devtools Network/Performance tabs to build a baseline for icon pack impact.

Step-by-step: Add a single custom icon (UI-first checklist for beginners)

This section is the hands-on flow you will follow. Start with HACS if possible; fallback to manual if not.

A) Single-icon quick path (HACS-first) — copy/paste UI clicks

1. Open HA UI and go to HACS > Frontend.
2. Click Explore & Download and search for “Custom Brand Icons“.
3. Click Download (or Install) and follow prompts to add the integration.
4. After install, go to Settings > Dashboards > Resources > + Add.
5. Paste resource URL: /local/community/custom-brand-icons/custom-brand-icons.js and set Type to module. Click Save.
6. Restart Home Assistant (recommended) via Settings > System > Restart.
7. Edit your Lovelace card, open the icon field and type an icon name with the prefix — e.g., phu:eggs — and save the card.

Example YAML fragment you can copy/paste into a manual card or automation UI (icon field):

icon: phu:eggs

B) Manual fallback (upload resource)

1. Download custom-brand-icons.js from the releases on the project repo: GitHub (2026-04-20).
2. Copy the file into /config/www/community/custom-brand-icons/ (use Samba, File Editor, or SCP).
3. In HA UI go to Settings > Dashboards > Resources > + Add.
4. Resource URL: /local/community/custom-brand-icons/custom-brand-icons.js, Type: module. Save and restart HA.

C) Assign the icon to an entity or card

1. Edit the dashboard card: click Edit > Configure UI > choose the card > open the Icon field and enter phu:iconname.
2. Example: icon: phu:eggs. For YAML cards you can paste the same line under the entity.

Sources and guides used for these steps: installation guidance at SmartHomeScene (2026-04-20) and the repo README (GitHub, 2026-04-20).

Pitfall to avoid: Do not use the wrong resource path (for example /local/custom-brand-icons.js) — the correct path for the package is /local/community/custom-brand-icons/custom-brand-icons.js.

Full library install: file naming, folder structure, and Lovelace resource mapping (scale safely)

When you want a complete pack of icons, follow this structure and naming conventions.

• Recommended folder structure: /config/www/community/custom-brand-icons/ (make sure permissions are writable by HA user). Repo examples and install instructions expect this path (GitHub, 2026-04-20).
• Naming convention: icons are exposed with the phu: prefix. Examples include phu:eggs, phu:chicken. Use the icon viewer in the package to find exact names.
• Add the resource in UI: Settings > Dashboards > Resources > + Add with URL /local/community/custom-brand-icons/custom-brand-icons.js, Type: module, then restart HA.
• HACS is preferred for updates and maintenance — it simplifies redownloads and uninstalls.

Batch verification (quick): after install, open your dashboard in a browser, run Ctrl+Shift+R, then open an incognito window to confirm icons load without cached assets.

Internal links for scaling and dashboards: the best dashboard home assistant, Home Assistant Raspberry Pi, and Build LCARS Home Assistant Dashboard provide larger-dashboard tips and file-access methods.

Icon image specs & performance numbers you must follow

Follow these image rules to avoid broken icons and slow dashboards.

• Format: SVG strongly recommended for crisp scaling and small files. Use PNG only as a fallback for very specific cases.
• Exact numbers: target native size and viewBox rules — use a 24×24px native area and include a proper viewBox. Community guidance: “24x24px native size” (Community thread, 2026-04-20) — community.home-assistant.io (2026-04-20).
• SVG best practices: single-path icons where possible, include a viewBox attribute, avoid transforms and nested groups that change size, and avoid embedded base64 images.
• Performance: no official limit on icon count found in sources. Recommended test: spot-check 10–50 icons on a busy dashboard and measure load time using browser devtools; there are no reliable benchmarks available (no reliable data found).

SVG validation snippet (head of file to check):

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"> ... </svg>

Pitfall to avoid: Broken SVGs without viewBox, incorrect scaling, or heavy base64 embedding that inflates file size and slows loading.

Troubleshooting checklist: fast diagnostics and fixes for common failure modes

Use this printable checklist to quickly isolate what went wrong.

• Symptom: icon missing in browser but shows in source? Diagnosis: open Developer Tools > Network and search for 404s to /local/community/custom-brand-icons/. Fix: verify file path and resource URL.
• Symptom: shows in browser but not mobile app? Diagnosis: mobile cache. Fix: force-refresh mobile app or clear its cache. Community reports aggressive mobile caching — see thread (2026-04-20): community.
• Symptom: icons broken or invisible? Diagnosis: inspect the SVG for missing viewBox or incorrect paths. Fix: correct SVG to 24×24 viewBox and single path.
• Symptom: HACS changes not applied? Diagnosis: stale HACS cache or old installed version. Fix: open HACS > Frontend > Custom Brand Icons and redownload or reinstall (GitHub, 2026-04-20).

Quick commands and checks (copy/paste actions):

• Browser hard reload: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS).
• Open DevTools > Network and filter for /local/community/custom-brand-icons/ to catch 404s or 500s.
• Restart Home Assistant: Settings > System > Restart.
• Test in incognito: open a private window to rule out cached assets or extensions.

Sources with fixes and notes: repo troubleshooting and path notes at GitHub (2026-04-20) and mobile cache reports at the community thread above (2026-04-20).

Verification, rollback & automation use-cases (confirm, undo, and automate)

Confirm icons are loaded and used by automations; know how to safely revert if needed.

Verification steps

• Browser: hard reload (Ctrl+Shift+R) and verify the icon appears in the card.
• Network: check DevTools Network for successful 200 on /local/community/custom-brand-icons/custom-brand-icons.js.
• HA restart: perform Settings > System > Restart after adding resources to ensure registration.
• Mobile: force-close and re-open the Home Assistant mobile app, or clear app cache; widgets may lag or not refresh until app cache clears (community, 2026-04-20).

Automation example (copy/paste)

action:
  - service: notify.mobile_app_yourphone
    data:
      title: "Device"
      message: "On"
      data:
        attachment:
          icon: "phu:eggs"

Rollback steps

1. Remove the Lovelace resource entry: Settings > Dashboards > Resources > delete the /local/community/custom-brand-icons/custom-brand-icons.js entry.
2. If installed via HACS: uninstall via HACS > Frontend > Custom Brand Icons > Uninstall.
3. Manual: delete the folder /config/www/community/custom-brand-icons/ from the filesystem.
4. Restart HA and clear browser/mobile caches to remove leftover assets.

Version-specific note: for Home Assistant 2026.3+ prefer the brands-proxy API for official integration icons when available; use custom-brand-icons only where brands-proxy lacks the desired icon. (See Developers blog: brands-proxy API (2026-02-24).)

Pitfall to avoid: After rollback, remember to remove the resource entry; leaving it will cause a broken module reference in Lovelace.

Conclusion

Follow the checklist above to add custom brand icons with minimal fuss: prefer HACS for speed and safety, use /config/www/community/custom-brand-icons/ for manual installs, register the resource URL /local/community/custom-brand-icons/custom-brand-icons.js (module), and use the phu: prefix in cards and automations. If you hit problems, run the troubleshooting checklist and restart both HA and the mobile app. To read more about dashboard best practices and file access, check the linked internal resources above.

Ready to add one now? Start with the HACS flow or manual copy and follow the printable checklist below. If you want in-depth setup for hardware, see Home Assistant Raspberry Pi.

FAQ

Printable one-page checklist

Troubleshooting tick-boxes

• ☐ Confirm resource URL loads (open /local/community/custom-brand-icons/custom-brand-icons.js in browser)
• ☐ Check Developer Tools > Network for 404s
• ☐ Hard reload browser + test incognito
• ☐ Restart Home Assistant
• ☐ Force-close mobile app and re-open; clear mobile cache if needed
• ☐ Validate SVG viewBox = “0 0 24 24”