{"id":13577227,"url":"https://github.com/Mariusthvdb/custom-ui","last_synced_at":"2025-04-05T11:31:46.161Z","repository":{"id":40364430,"uuid":"267558148","full_name":"Mariusthvdb/custom-ui","owner":"Mariusthvdb","description":"Add templates and icon_color to Home Assistant UI","archived":false,"fork":false,"pushed_at":"2024-09-16T09:10:17.000Z","size":1338,"stargazers_count":161,"open_issues_count":0,"forks_count":30,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-09-16T10:44:41.632Z","etag":null,"topics":["attributes","customization","icon-color","more-info","templates"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mariusthvdb.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-28T10:17:15.000Z","updated_at":"2024-09-16T09:10:21.000Z","dependencies_parsed_at":"2023-12-14T10:53:21.480Z","dependency_job_id":"c29d5656-95ad-437a-bba2-f02f8b95ac3b","html_url":"https://github.com/Mariusthvdb/custom-ui","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mariusthvdb%2Fcustom-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mariusthvdb%2Fcustom-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mariusthvdb%2Fcustom-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mariusthvdb%2Fcustom-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mariusthvdb","download_url":"https://codeload.github.com/Mariusthvdb/custom-ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223186485,"owners_count":17102471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attributes","customization","icon-color","more-info","templates"],"created_at":"2024-08-01T15:01:19.513Z","updated_at":"2024-11-05T14:30:40.010Z","avatar_url":"https://github.com/Mariusthvdb.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# What is Custom-ui\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)\n[![GH-release](https://img.shields.io/github/v/release/Mariusthvdb/custom-ui.svg?style=flat-square)](https://github.com/Mariusthvdb/custom-ui/releases)\n[![GH-downloads](https://img.shields.io/github/downloads/Mariusthvdb/custom-ui/total?style=flat-square)](https://github.com/Mariusthvdb/custom-ui/releases)\n[![GH-last-commit](https://img.shields.io/github/last-commit/Mariusthvdb/custom-ui.svg?style=flat-square)](https://github.com/Mariusthvdb/custom-ui/commits/master)\n[![GH-code-size](https://img.shields.io/github/languages/code-size/Mariusthvdb/custom-ui.svg?color=red\u0026style=flat-square)](https://github.com/Mariusthvdb/custom-ui)\n\n## Please read this before using custom-ui\n\nCustom-ui was developed a long time ago, before Home Assistant introduced the modern Dashboard (Lovelace). Home Assistant has evolved significantly since then, so most users no longer need custom-ui.\n\n[Theming](https://www.home-assistant.io/integrations/frontend/#defining-themes) and the use of [state-colors](https://www.home-assistant.io/integrations/frontend/#supported-theme-variables) in the Frontend have become very powerful and should be your first choice for customizing colors based on states.\n\nIf you need more, especially if you want to use templates, consider using the custom [Card-mod](https://github.com/thomasloven/lovelace-card-mod), which allows the user to modify almost anything in the Dashboard views (the Frontend).\n\nOnly as a last resort should you consider using custom-ui, and only in those cases where you need more power and control.\n\nThe use of the templating feature on all attributes (yes, custom-ui is that powerful) should be discouraged because it interferes with entities in the Home Assistant state machine (the back-end).\n\nThe Core development team consistently emphasizes the importance of maintaining as clean a state machine as possible and warns against overloading it with (custom) attributes, especially templating those attributes.\n\n**So, again, only use custom-ui if you know what you are doing and if no other option is available.**\n\n______\n\nWe can \n[customize entities in core Home Assistant](https://www.home-assistant.io/docs/configuration/customizing-devices/). \nHowever, this is rather limited. Two of the most important features Custom-ui offers on top of the \ncore customization are support for:\n* **Templates** \n* **icon_color** attribute.\n\nWe can use these features **globally** in our Home Assistant configuration and thus create extremely powerful yet \nvery compact customizations. Added to that, custom-ui allows one to **hide attributes** from the \nmore-info pane. Check the [examples](https://github.com/Mariusthvdb/custom-ui/blob/master/EXAMPLES.md) \nhow.\n\n\u003cimg width=\"492\" alt=\"icon-color\" src=\"https://user-images.githubusercontent.com/33354141/168234088-ee5a5b11-0e68-49fd-b664-6e5a13c79fb0.png\"\u003e\n\n## Development of this plugin, strategy forward\n\nPlease see the pinned [discussion](https://github.com/Mariusthvdb/custom-ui/discussions/128) on development of this plugin.\n\nIn short:\n- If you want a tool to customize icon_color: Use either custom-ui (with template support) or custom-icon-color.\n- If you want a tool to customize more-info dialogs: Use custom-more-info\n\nCurrent custom-ui (with legacy more-info manipulation) will be archived, and renamed, so we can keep the custom-ui name for the current custom-ui-only.\n\n## NEWS\n\n**New Custom template attributes**\n\nAll modifications in my entire config are now implemented using [Card-mod](https://github.com/thomasloven/lovelace-card-mod). I am aware this only works in the actual cards in the View, and not on the more-info dialog of entities.\nIt is an acceptable trade-off between optimal desktop customization, and optimal core handling of the state machine. \n\nIn the end, the best way forward is to avoid overloading the state machine with custom elements as much as possible..\n\nThere is only 1 modification I 'need', that can't be done with card-mod.\n\nMy person's entity_picture need to grayscale when `not_home`, specifically in the [`type: map`](https://www.home-assistant.io/dashboards/map/) cards. \nCurrently we can succesfully set a css filter in most other regular cards with card-mod, but those modifications do not affect the Map card.\nFor that purpose, and that purpose alone, this new `custom-attributes-templates` now sees the light.\n\nIn all honesty, I hope this can be deleted as soon as core Home Assistant would provide other means to do so. \nThere is however not a single hint entity_picture will ever be leveraged (we can not even set an [entity_picture in the UI](https://www.home-assistant.io/docs/configuration/customizing-devices/#customizing-an-entity-in-yaml) and need [`customize:` in Yaml](https://www.home-assistant.io/integrations/homeassistant/#manual-customization) for that), eg. like we can now do with [state-colors](https://www.home-assistant.io/integrations/frontend/#supported-theme-variables).\n\nUntil that moment, this will have to do:\n\n```\nhomeassistant:\n\n  customize_domain:\n\n    person:\n      templates:\n        entity_picture: \u003e\n          var id = entity.entity_id.split('.')[1];\n          return state === 'not_home'\n          ? '/local/family/' + id + '_not_home.png' : '/local/family/' + id + '.jpg';\n```\n\nI purposely do NOT provide an easy way to download it via HACS, or plan a release. The file can be downloaded from the list above, and installed like any other resource:\n\n```\n- url: /local/resources/custom-attributes-templates/custom-attributes-templates.js?v=202400815\n  type: module\n```\n\n**New Custom More-info**\n\n[Custom More-info](https://github.com/Mariusthvdb/custom-more-info) is a new custom Plugin for Home Assistant and superseeds the plugin `custom-attributes` announced below. \n\nNext to the functionality of `custom-attributes`, with `custom-more-info` users can customize when and when not to display the History and Logbook sections in the More-info card. Even hide the History icon in the Header completely. Automatically, or based on manual settings.\n\nFrom now on you are in control of the More-info attributes and all other sections. Filter all, unfilter all, or select which to see/hide by glob, domain, device_class, or entity_id. Any combination is possible!\n\nCustom More-info gives the user ultimate control over the More-info panel.\n___\n**New Custom Attributes**\n\n[Custom attributes](https://github.com/Mariusthvdb/custom-attributes) is a new resource for Home Assistant to customize which entity attributes are displayed in the Dashboard on more-info cards. Moreover, if configured so that no more attributes are left to display (all attributes are filtered), the attributes dropdown box is not rendered at all. This is replacing that specific functionality from Custom-ui.\n\n### DON'T INSTALL BOTH CUSTOM-ATTRIBUTES AND CUSTOM-MORE-INFO SIMULTANEOUSLY. USE ONLY 1 OF THESE 2 NEW PLUGINS\n___\n**New Custom icon_color**\n\nA new custom-ui sibling was released, [custom-icon-color](https://github.com/Mariusthvdb/custom-icon-color), which can be used *only* for adding an attribute in `customize:` and the attributes configuration options of [template:](https://www.home-assistant.io/integrations/template/#attributes) entities.\n\n*No more templates possible* with this version, which minimizes impact on the HA system and Frontend if you wish to do so. There was never a huge impact, but this brings it down even further, if you don't need the template options and still want the icon_color attribute in your options.\nConfiguration is identical to what is already explained in the example section\n\n___\n**Did you know....**: custom-ui facilitates setting a [Jinja template on custom attributes](https://github.com/Mariusthvdb/custom-ui/blob/master/EXAMPLES.md#did-you-know) in core integrations that allow setting a custom attribute.\n\n--- \n\n## Installation\n\n\n### Manual Installation\n\n1. Download the [custom-ui](http://www.github.com/Mariusthvdb/custom-ui/releases/latest/download/custom-ui.js)\n2. Place the file in your `config/www` folder or any subfolders.\n3. Include the card code in your `ui-lovelace-card.yaml`\n\n   ```yaml\n   title: Home\n   resources:\n     - url: /local/custom-ui.js\n       type: module\n   ```\nor when using the UI, click \n\n\u003ca href=\"https://my.home-assistant.io/redirect/lovelace_resources/\" target=\"_blank\"\u003e\u003cimg src=\"https://my.home-assistant.io/badges/lovelace_resources.svg\" alt=\"Open your Home Assistant instance and show your Lovelace resources.\" /\u003e\u003c/a\u003e\n\n### Installation and tracking with `hacs`\n\n1. Make sure the [HACS](https://github.com/custom-components/hacs) component is installed and working.\n2. Search for `custom-ui` and add it through HACS\n3. Add the configuration to your `ui-lovelace.yaml`\n\n   ```yaml\n   resources:\n     - url: /hacsfiles/custom-ui/custom-ui.js\n       type: module\n   ```\n\n4. Refresh home-assistant.\n\n### Other installation methods\nSee [INSTALLING](https://github.com/Mariusthvdb/custom-ui/blob/master/INSTALLING.md)\n\n## Examples\nSee [EXAMPLES](https://github.com/Mariusthvdb/custom-ui/blob/master/EXAMPLES.md).\n\nFor card-mod replacement mods, see [CARD-MOD-EXAMPLES](https://github.com/Mariusthvdb/custom-ui-icon-color/blob/main/CARD-MOD-EXAMPLES.md)\n\n---\n\n## Learn core Home Assistant customization \nIt goes without saying that custom-ui is an extension of core Home Assistant functionality. As \nsuch, you should understand what is documented on \n[Homeassisant.io](https://www.home-assistant.io/docs/configuration/customizing-devices/) about the \nsubject. \n\nImportant to note, is that Home Assistant \n[core Jinja templating](https://home-assistant.io/docs/configuration/templating/) is calculated in \nthe back-end, server side, (the device Home Assistant is running on). Custom-ui Javascript \ntemplating is calculated in the front-end, browser side, (the device Home Assistant is displayed \non). \n\nHeavy templating might impact the performance of the system and will depend on processor power and \nmemory available on either side of your devices.\n\n### Caveats\nCustom-ui can't customize everything. Entities created in python scripts (you need to set the \ncustomization in the script itself) and entities created by several add-ons can't be touched by \ncustom-ui. E.g. Home Assistant Google Drive Backup. You can work \naround that by creating template sensors for those entities, which you can again customize in HA.\n\nAlso, do notice that changes to configuration used by this plugin will only apply on the state\nchange of the related entity. Thus, if you have already reloaded your new YAML config via Developer\nTools \u003e YAML \u003e Location \u0026 Customizations, but it didn't \"kick in\", try to force a state change in\nthe entity you're testing\n\n### Not all Lovelace cards are equal\nNot all core HA cards use the same icon handling. Because of that, cards like\n* [Picture-glance card](https://www.home-assistant.io/dashboards/picture-glance/)\n* [Statistic card](https://www.home-assistant.io/dashboards/statistic/)\n\nare not customized by `custom-ui`.\n\nThomas Loven's [Card-mod](https://github.com/thomasloven/lovelace-card-mod), which is an amazing \nplugin for Lovelace with many features, to the rescue.\n\n### Interaction with Card-mod\nBe aware that custom-ui is very impactful. As a matter of fact, it is 'stronger' than card-mod. \nMeaning if you have e.g. a `customize_glob` on `icon_color` set using custom-ui, any card-mod \nconfig won't work.\n\n### Credits\nI've been a longtime and heavy user of custom-ui, and this is the place to applaud Andrey for his \namazing plugin. Home Assistant wouldn't be the same without the global customizing it enables us \nto do. Couldn't live without it! All credits go to @andrey-git.\nYou can read up on a bit if \n[history](https://github.com/Mariusthvdb/custom-ui/blob/master/HISTORY.md) how it came to this \nadapted version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMariusthvdb%2Fcustom-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMariusthvdb%2Fcustom-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMariusthvdb%2Fcustom-ui/lists"}