Noureddine RAMDI / Person Tracker Card for Home Assistant: Visualizing Presence with a Custom Dashboard Card

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
913 Words
github-stars home assistant javascript custom cards dashboard companion app iot

djdevil/person-tracker-card

Visualizing presence and location of household members in Home Assistant dashboards is a common need that many users find tricky to achieve with default cards. The Person Tracker Card project offers a focused solution: a customizable dashboard card that surfaces person entities with rich sensor data from the Home Assistant Companion App, presenting presence, location, and activity in a clear, configurable layout.

What the person tracker card does and how it integrates with Home Assistant

Person Tracker Card is a frontend custom card written in JavaScript designed specifically for Home Assistant dashboards. It extends the dashboard UI by providing a more detailed and dynamic visualization of person entities compared to the built-in cards.

Under the hood, it leverages data exposed by the Home Assistant Companion App, which enhances person entities with various sensors such as GPS location, motion, and device status. The card auto-detects these sensors and presents them in a user-friendly layout, allowing users to pick a person entity and configure which sensors to display.

The architecture is typical of modern Home Assistant custom cards: JavaScript modules loaded as resources into the Lovelace dashboard. This means it runs entirely in the browser, interacting with the Home Assistant frontend API to pull entity states and update in real-time.

The stack is lightweight: just two JavaScript files (person-tracker-card.js and person-tracker-card-editor.js), which handle the card rendering and the card configuration editor respectively. This simplicity keeps the footprint small and the integration smooth.

Technical strengths and design tradeoffs

One of the card’s main strengths is its seamless integration with the Companion App’s sensors. By auto-detecting relevant sensors tied to a person entity, it saves users from manually specifying many sensor entities. This improves the developer experience and reduces setup errors.

It also supports dynamic entity pictures via YAML templates, which means you can customize the visual representation of each person based on their state. For example, swapping GIFs depending on presence state adds personality to your dashboard.

The code is surprisingly clean for a UI card of this scope, with clear separation between the card component and the editor component. The use of JavaScript modules aligns with modern frontend practices recommended by Home Assistant.

The tradeoff here is the manual installation process if you prefer not to use the Home Assistant Community Store (HACS). Manual steps require copying files to the right directory and updating Lovelace resources, which can be error-prone. However, HACS installation is straightforward and recommended.

Another limitation is the dependency on the Companion App sensors. If you don’t use the Home Assistant mobile app or don’t expose sensors for your person entities, the card’s richness diminishes.

Quick start with Person Tracker Card

Installation can be done via HACS, which is the recommended path for most users.

Note: If the HACS button doesn’t work, follow the manual installation steps below.

  1. Open HACS in your Home Assistant UI.
  2. Click the ⋮ menu in the top right and choose Custom repositories.
  3. Add the repository URL: https://github.com/djdevil/person-tracker-card.
  4. Set the category to Dashboard and click Add.
  5. Search for Person Tracker Card and click Download.
  6. Restart Home Assistant to apply the changes.

Manual installation

  1. Download the files person-tracker-card.js and person-tracker-card-editor.js from the repository.

  2. Copy them to your Home Assistant config/www/person-tracker-card/ directory.

  3. Add a new Lovelace resource:

    • Path: /local/person-tracker-card/person-tracker-card.js
    • Type: JavaScript Module

  4. Hard refresh your browser (Ctrl+Shift+R) to load the new resource.

Using the card in your dashboard

In the Lovelace UI editor:

  1. Edit your dashboard and add a new card.
  2. Search for Person Tracker Card.
  3. Select a person entity to track.
  4. Choose a layout and configure which sensors to display.

You can also customize the entity picture dynamically with YAML templates, for example:

entity_picture: /local/marco-home.gif

Or use a template sensor to swap images based on state.

Verdict

Person Tracker Card is a practical, focused tool for Home Assistant users who want more detailed presence and location visualization on their dashboards. It fills a niche where the default person cards fall short by integrating Companion App sensors and providing flexible layouts.

The installation via HACS is smooth and recommended, but the manual steps are clearly documented for those preferring direct control. The reliance on the mobile app’s sensors is a limitation, so it’s best suited for setups that already use the Companion App extensively.

Overall, if you use Home Assistant and want to enhance your dashboard’s person tracking capabilities with minimal fuss and a clean UI, this card is worth exploring. It’s a solid example of how custom cards can extend Home Assistant’s frontend with targeted, practical features.

→ GitHub Repo: djdevil/person-tracker-card ⭐ 199 · JavaScript