How To Add Custom Icons in Home Assistant

With any Home Assistant installation, a Material Design icon pack is included by default. With version v7.1, this pack includes over 7000 custom icons that you can use for your entities or cards.

The developers of Material Design Icons, called Pictogrammers, recently moved to a new website, making it faster, easier and cleaner to browser through icons before adding any to Home Assistant. If you want to help improve this project, you can do so by clicking contribute on their website.

However, more advanced HA users and tinkerers know that sometimes this default icon pack does not contain just what you are looking for. We are going to look at some custom icon packs available in the community store and showcase how you can use them in Home Assistant.

Any of the mentioned icon packs can be installed via HACS.

Custom Brand Icons

This icon pack is developed and maintained by elax46 and provides a bunch of pretty awesome SVG icons from different brands such as Apple, Google, Amazon (Alexa), Aqara, Phillips Hue, Reolink:

Aside from brand icons, this pack includes custom icons for: Doors, Car Manufacturers, HA Addons, House Rooms, Modem/Router ISP, Window/Shutters, Television, Vacuums, Batteries Status and much more!

Installation:

<< Click OR:
- Navigate to HACS > Frontend
- Click + Explore & Download Repositories
- Search for Custom Brand Icons
- Click Download
- Add resource reference as an extra_module_url
- Restart Home Assistant
Manual
- Download custom-brand-icons.js file from the latest release.
- Copy the custom-brand-icons.js file into <config>/www/
- Add resource reference as an extra_module_url
- Restart Home Assistant

frontend: #Resource Reference, adjust URL if needed
  extra_module_url:
    - /local/community/custom-brand-icons/custom-brand-icons.js

Usage:

To use it, instead of the usual mdi: you need to add the prefix phu:

type: entity
entity: light.living_room
icon: phu:pendant-round

Example (entities card):

Hass Hue Icons

This icon pack by developer arallsopp offers a bunch of vector icons to better represent Phillips Hue bulbs, pendant and fixtures. Considering the Hue range of these types of devices, it amounts to 72 official and 400+ additional user requested icons you can use in Home Assistant.

This icon pack includes a ‘keyword’ search functionality. Meaning, you do not need the correct name when searching for icons within Home Assistant, just a generic category keyword: e.g. pendant.

Installation:

<< Click OR:
- Navigate to HACS > Frontend
- Click + Explore & Download Repositories
- Search for Hass Hue Icons
- Click Download
- Add resource reference as an extra_module_url
- Restart Home Assistant
Manual
- Download hass-hue-icons.js file from the latest release.
- Copy the hass-hue-icons.js file into <config>/www/
- Add resource reference as an extra_module_url
- Restart Home Assistant

frontend: #Resource Reference, adjust URL if needed
  extra_module_url:
    - /local/community/hass-hue-icons/hass-hue-icons.js

Usage:

To use it, instead of the usual mdi: you need to add the prefix hue:

type: entity
entity: light.living_room
icon: hue:ceiling-adore-flush

Example (entities card):

KUF User Forum Icons

This particular icon set by dev mampfes contains more than 900 icons based on the KNX User Forum. Icons range from simple media control buttons, internal and garage doors, weather icons and so much more. This icon pack provides an alternative to the built-in Material Design icons. The full list of available icons can be found here.

Installation:

<< Click OR:
- Navigate to HACS > Frontend
- Click + Explore & Download Repositories
- Search for KNX User Forum Icon Set
- Click Download
- Add resource reference as an extra_module_url
- Restart Home Assistant
Manual
- Download ha-knx-uf-iconset.js file from the latest release.
- Copy the ha-knx-uf-iconset.js file into <config>/www/
- Add resource reference as an extra_module_url
- Restart Home Assistant

frontend: #Resource Reference, adjust URL if needed
  extra_module_url:
    - /local/community/ha-knx-uf-iconset/ha-knx-uf-iconset.js

Usage:

To use it, instead of the usual mdi: you need to add the prefix kuf:

type: entity
entity: light.living_room
icon: kuf:light_ball

Example (entities card):

Troubleshooting

If you are not seeing the custom icons you just added, you need to check for a few things, the most important being the correct URL of the resource reference:

Correct extra_module_url: HACS Installation:

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

Correct extra_module_url: Manual Installation in <config>/www/:

frontend:
  extra_module_url:
    - /local/custom-brand-icons.js #OR adjust to your folder structure

(Optional) Adding a resource reference: HACS Installation:

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

(Optional) Adding a resource reference: Manual Installation <config>/www/:

resources:
  - type: js
    url: /local/custom-brand-icons.js #OR adjust to your folder structure

The most common cause for icons not being displayed on accessible through the icon browser once the reference URL is correct is caching issues:

Clear Cache (Ctrl + F5)
Test in Incognito Mode
Restart Home Assistant

If you are still having trouble clearing your cache, see this guide which explains it by browser type.

Summary

If you are on the hunt for some additional customization, I suggest you take a look at the mentioned custom icons pack. I’ve found the Custom Brand Icons Pack covers almost everything I need to customize my dashboard.

The great thing is once you input the prefix in the dashboard editor (phu, hue or kuf) the icons will be listed and you can simply browser through them and pick the one you want. Please note that this is card dependent, as not all card come with a built-in UI editor. For some, you will need to use YAML and check the icon names on their respective Github repos.