{"id":13613797,"url":"https://github.com/postlund/home-card","last_synced_at":"2025-05-12T03:31:45.553Z","repository":{"id":35527731,"uuid":"173693234","full_name":"postlund/home-card","owner":"postlund","description":"A quick glance of the state of your home in Home Assistant Lovelace UI.","archived":false,"fork":false,"pushed_at":"2023-04-04T20:13:01.000Z","size":592,"stargazers_count":196,"open_issues_count":10,"forks_count":20,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-31T23:43:08.523Z","etag":null,"topics":["home-assistant","home-assistant-custom","home-automation","lovelace","lovelace-ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postlund.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["postlund"]}},"created_at":"2019-03-04T07:14:28.000Z","updated_at":"2025-03-18T19:13:09.000Z","dependencies_parsed_at":"2024-01-05T21:05:37.056Z","dependency_job_id":null,"html_url":"https://github.com/postlund/home-card","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlund%2Fhome-card","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlund%2Fhome-card/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlund%2Fhome-card/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlund%2Fhome-card/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postlund","download_url":"https://codeload.github.com/postlund/home-card/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253668063,"owners_count":21944969,"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":["home-assistant","home-assistant-custom","home-automation","lovelace","lovelace-ui"],"created_at":"2024-08-01T20:00:53.714Z","updated_at":"2025-05-12T03:31:44.975Z","avatar_url":"https://github.com/postlund.png","language":"JavaScript","funding_links":["https://github.com/sponsors/postlund"],"categories":["Lovelace User Interface","Install from Source","Dashboards"],"sub_categories":["Custom Lovelace UI Cards","Smart Home Automation","Custom Cards"],"readme":"# Home Card\n\nA quick glance of the state of your home in [Home Assistant](https://github.com/home-assistant/home-assistant) Lovelace UI.\n\n![Demo of card](images/demo.gif)\n\nInitial work on UI editor (only some options can be edited):\n\n![UI Editor](images/card-editor.png)\n\n*Note: This card is still in early development (preview/proof-of-concept), beware of bugs and lacking features!*\n\n## Features\n\n* Graphical representation of your home with different themes\n* Displays things such as weather, state of lights and garage door as well as arbitrary sensors\n* Lovelace UI editor for some options (still early work)\n* Flexible tap and hold actions (same as for entity-button)\n* Create your own custom themes!\n* Transparent or regular paper card background\n\n## Roadmap\n\nSome things I want to add in upcoming releases:\n\n* More house types and better graphics\n* Extend with additional overlays for things like alarm, people and doors\n* More ways to customize how the card looks and feel\n* Extend or override existing themes using `custom_themes`\n* More improved Lovelace UI editor\n* Support for custom_updater\n* Better development environment with linting, etc.\n\n## Install\n\n### Simple Install\n\n1. Download `home-card.js`, `themes.js` and `themes` and copy them into `config/www/home-card` (create the `home-card` directory)\n\n2. Add a reference to `home-card/home-card.js` inside your `ui-lovelace.yaml`\n\n  ```yaml\n  resources:\n    - url: /local/home-card/home-card.js?v=0\n      type: module\n  ```\n\n### Git Install\n\n1. Clone this repository into your `www`-directory: `git clone https://github.com/postlund/home-card.git`\n\n2. Add a reference to `home-card/home-card.js` inside your `ui-lovelace.yaml`\n\n  ```yaml\n  resources:\n    - url: /local/home-card/home-card.js?v=0\n      type: module\n  ```\n\n### Custom updater\n\nNot using this yet...\n\n## Updating\n\nIf you...\n\n* manually copied the files, just download the latest files and overwrite what you already have\n* cloned the repository from Github, just do `git pull` to update\n\n... and increase `?v=X` to `?vX+1`.\n\n## Using the card\n\n### Card layout\n\nThe card is split into three different areas:\n\n![Structure of card](/images/structure.png)\n\nExplanation of each area:\n\n* Weather area (Red): Displays current weather with an icon (e.g. sun or cloud) and temperature. Name of location is displayed as well. Controlled by the `weather` option.\n* House area (Green): Main visualization of the house. Consists of `overlay` images that can be shown or hidden depending on an entity state. A car overlay (image) can for instance be shown if `device_tracker.car` has the state `home`. Controlled by the `entities` option.\n* Resources (Blue): Simplistic view of sensors. Controlled by the `resources` option.\n\nBoth the weather and resources areas are optional and will not displayed if omitted from the configuration. The house area are however mandatory.\n\n### Options\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| type | string | **required** | `custom:home-card`\n| theme | string | **required** | Name of a theme, see [supported themes](#supported-themes)\n| background | string | transparent | Supported values: empty, `transparent`, `paper-card`\n| weather | string | optional | `weather` entity used for displaying location and temperature\n| entities | object | optional | List of [entity objects](#entity-object)\n| resources | object | optional | List of [resource objects](#resource-object)\n| custom_themes | object | optional | List of [theme objects](#theme-object)\n\n#### Supported themes\n\nThe following themes and overlays are currently supported:\n\n| Theme | Overlays |\n|------|----------|\n| two_story_with_garage | door, garage, outside_light, upstairs_light, downstairs_light, car, sprinkler\n\nThese states are supported by the overlays:\n\n| Overlay | States | Component examples |\n|---------|--------|-----------------------|\n| car | home, not_home | device_tracker\n| door | on, off | E.g. binary_sensor, switch\n| downstairs_lights | on, off | E.g. light, binary_sensor\n| garage | open, closed | cover\n| outside_light | on, off | E.g. light, binary_sensor\n| upstairs_lights | on, off | E.g. light, binary_sensor\n| sprinkler | on, off | E.g. binary_sensor, switch\n\nYou may add additional state mappings using a `state_map` to support other component types, see [Entity object](#entity-object).\n\n#### Entity object\n\nAn `entity object` maps an entity in Home Assistant to an overlay in the card, e.g. which `device_tracker` entity that shows/hides the car or which `light` that corresponds to \"upstairs\".\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| type | string | **required** | Overlay type, see [overlay tabe](#supported-themes)\n| entity | string | **required** | Entity id from Home Assistant, e.g. `light.downstairs`\n| state_map | map | optional | Key-value map of state (in Home Assistant) to overlay state\n\nA simple example of an entity object in yaml looks like this:\n\n```yaml\n- type: car\n  entity: binary_sensor_.car\n  state_map:\n    on: home\n    off: not_home\n```\n\nThis object supports custom [tap and hold actions](#tap-and-hold-actions).\n\n#### Resource object\n\nA `resource` is a simple sensor that is displayed beneath the house, e.g. a temperature sensor or water usage. You can use any entity but you might have to manually specify an `icon` and/or `unit_of_measurement`.\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| entity | string | **required** | An entity from Home Assistant, e.g, `sensor.water_usage`\n| icon | string | optional | Override icon to use, e.g. `mdi:car`\n| unit_of_measurement | string | optional | Override unit of measurement, e.g. `lux`\n\nA simple example of a resource object in yaml looks like this:\n\n```yaml\n- entity: sensor.water_usage\n  icon: mdi:water\n  unit_of_measurement: liter\n```\n\nThis object supports custom [tap and hold actions](#tap-and-hold-actions).\n\n#### Theme object\n\n**THIS IS EXPERIMENTAL AND MAY BREAK LATER - BEWARE!**\n\nYou can define your own themes and use your own images if you like. Some things to consider:\n\n* Keep images small (in size) to keep everything snappy\n* Re-use overlays and names as much as possible to keep themes consistent\n* If you make a cool looking theme, feel free to send a PR (make sure to clarify where images come from to cope with licenses) and remember to include a screenshot\n* It is currently not possible to alter/extend existing themes, only define additional themes\n\nThe format of this object will be described in more detail once the format has been set, but have a look at the [example](#creating-custom-themes) to see how you configure your theme in current state.\n\n### Tap and hold actions\n\nThis card supports custom `tap` and `hold` actions for most things available in the card. Each theme defines the default behavior for how `tap` and `hold` works, but you may freely override this behavior. The exact same format as used by the `entity button` in lovelace is used here.\n\nThe following options are valid for `tap_action` and `hold_action`:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| action | string | **required** | Action to perform, one of: `more-info`, `toggle`, `call-service`, `navigate`, `none`\n| navigation_path | string | optional | Where to navigate (e.g. `/lovelace/1`) when `action` is `navigate`\n| service | string | optional | Service to call (e.g. `switch.turn_on`) when `action` is `call-service`\n| service_data | string | optional | Service data to include when calling a service (e.g. `entity_id: switch.bedroom`).\n\nTo see an example, click [here](#using-custom-tap-and-hold-actions).\n\n### Example usage\n\n#### Defining a home\n\nSimple example using basic features:\n\n```yaml\n- type: 'custom:home-card'\n  theme: two_story_with_garage\n  weather: weather.home\n  entities:\n    - type: garage\n      entity: cover.garage_door\n    - type: upstairs_light\n      entity: light.demo_upstairs_light\n    - type: downstairs_light\n      entity: light_downstairs_light\n    - type: car\n      entity: device_tracker.car\n  resources:\n    - entity: utility meter.water\n    - entity: utility meter.electricity\n    - entity: binary_sensor.movement_backyard\n      icon: 'mdi:alarm-light'\n    - entity: sensor.outside_temperature\n      icon: 'mdi:thermometer'\n```\n\n#### Using custom tap and hold actions\n\nSimple example using various `tap` and `hold` actions:\n\n```yaml\n- type: 'custom:home-card'\n  theme: two_story_with_garage\n  entities:\n    - type: car\n      entity: device_tracker.car\n      tap_action:\n        action: navigate\n        navigation_path: /lovelace/2\n      hold_action:\n        action: more-info\n  resources:\n    - entity: sensor.outside_temperature\n      tap_action:\n        action: call-service\n        service: switch.turn_on\n        service_data:\n          entity_id: switch.fan\n      hold_action:\n        action: none\n```\n\n#### Re-mapping states\n\nHere, the `car` type is used as an example. It requires the specified entity to be a `device_tracker` as it maps states like `home` and `not_home` to different overlays. But you can add additional mappings to support for instance a `binary_sensor` as well using `state_map`, like below:\n\n```yaml\n- type: 'custom:home-card'\n  theme: two_story_with_garage\n  entities:\n    - type: car\n      entity: binary_sensor.car\n      state_map:\n        on: home\n        off: not_home\n```\n\n#### Creating custom themes\n\nYou can define you own themes quite simply using `custom_themes`. The basic structure looks like below (`car` is used to illustrate, you may add as many overlays as you like):\n\n```yaml\n- type: 'custom:home-card'\n  theme: my_home\n  entities:\n    - type: car\n      entity: device_tracker.car\n  custom_themes:\n    my_home:\n      house: house.png\n      overlay_actions:\n        '*':\n          tap_action:\n            action: toggle\n        car:\n          tap_action:\n            action: more-info\n      overlays:\n        car:\n          home:\n            - image: car_home.png\n              style:\n                left: 10%\n                top: 10%\n          not_home:\n            - image: car_away.png\n              style:\n                left: 40%\n                top: 40%\n```\n\nSome notes here:\n\n* You can defined multiple images for each state if you like (as a list is used)\n* `style` translates to CSS style attributes, so you may use any CSS attributes here\n* The theme is called `my_home`, so a directory with the same name must be created in the `themes` directory and all images placed there\n* The `house` option is the main backdrop image and must be defined\n* Overlay name (e.g. `car`) corresponds to `type` you specify under `entities` and may be anything you like (but try to be consistent with other themes to simply for other users in case you share your theme)\n* If an entity in Home Assistant has a state that is not defined by its corresponding overlay, no overlay will be shown\n* Different `tap_action` and `hold_action` configurations can be defined for specific overlay taps (like for 'car' in the example) or for all overlays using `*`.\n\n## Issues and imitations\n\n* Very limited lovelace editor support\n* Only one theme built-in\n\n## Getting errors?\n\nClear the browser cache, restart Home Assistant and make sure the configuration is correct.\n\nIf you believe you have found an error, please write an issue.\n\n## External resources\n\n\n### Images\n\nThis card uses some great free resources from Freepik, namely these:\n\n* [Weather Icons](https://www.freepik.com/free-vector/weather-icons-collection_972339.htm)\n* [House](https://www.freepik.com/free-vector/residential-houses-collection-flat-style_2065378.htm)\n* [Car](https://www.freepik.com/free-vector/flat-car-different-views_1504979.htm)\n\n### Other resources\n\nThe excellent `clear` theme is used in demo graphics, you can find it here:\n\nhttps://community.home-assistant.io/t/clear-theme/100464\n\nBackground image is linked from the same page as well.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlund%2Fhome-card","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostlund%2Fhome-card","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlund%2Fhome-card/lists"}