Map: add marker badges by ildar170975 · Pull Request #51435 · home-assistant/frontend

ildar170975 · 2026-04-07T03:06:42Z

Breaking change

Proposed change

Adds an optional badge for a marker on a Map.
Examples are below.
UI for setting the new options will provided later.

Options of a badge (all are optional):
entity - entity_id to be processed;
label_mode – can be label, state, attribute, icon, image;
label: string - only processed if label_mode: label; used to display a state/attribute value or any text;
attribute – chooses an attribute; only processed if label_mode: attribute;
unit – sets a unit for an attribute value; only processed if label_mode: attribute;
image – overrides an entity picture if an entity is defined; or set a picture if no entity defined;
icon – overrides an entity icon if an entity is defined; or set an icon if no entity defined;
color - affects label & icon;
background_color – as it says;
state_color – similar to other cards; only processed for domains which support colors;
hide_unit (true/false) – omit a unit for compactness; applied both to a state & attribute.

Notes:

The badge cannot be not applied to a zone.
Tapping on a badge shows a more-info popup (if entity is provided).
Wrong config for a badge (for example, label_mode: attribute w/o defining entity or attribute options) causes displaying a standard mdi:alert icon.
Position of a badge is set as follows: align with a top-right corner of a marker (with border-radius: 0) with an offset = ¼ of a badge size:

RTL is supported for a badge position (a badge is shown in a top-left corner in RTL).
You can show values w/o a unit with hide_unit option (both for a state & attribute).
A unit option of a badge is only processed for label_mode: attribute case; intended to set a unit for unitless attributes (also, can be used to add an additional suffix if an attribute does have a unit).
borderColor property is “inherited” from a marker (affects on a border-color css property of a badge).
By default, a font-size for a label is automatically increased a bit if hide_unit option is set. It is possible to set own font-size by a new CSS variable --ha-marker-badge-font-size (overrides that automatic increasing, thus same font-size will be used whether hide_unit is set or not).
A new CSS variable --ha-marker-badge-border-radius can be used; default radius is 50%.
Generated YAML code is “normalized” (options are set in a default order) as soon as a user changes something in UI editor to preserve consistency.

Next steps:

Add UI for badge options.
Add badge visibility conditions: can be used for scenarios like "only show badges on a large screen", "only show a battery level if < 50%".

Possible improvements:

Currently a badge shows a ha-svg-icon element for erroneous config with mdi:alert icon - like a state-badge element – with same fce588 color. Perhaps this color should be defined somewhere as a variable.

Possible use-cases are shown in examples below, like:

Show a battery level of a phone of a person or some device_tracker entity. Similarly - show a speed of a vehicle.
Show an icon of a particular device if a person has a few devices.
Show an image of a driver of a vehicle.

Examples:
Minimal config:

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.battery_1

If an entity has entity_picture:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      entity: sensor.marker_1

Show a text label (entity may be NOT defined – unless you need to get an additional logic & info in more-info) – could be a name of a device / vehicle / person / pet / ...:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      label_mode: label
      label: Bmw
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.kia_car
      label_mode: label
      label: KIA

Show an icon (entity may be NOT defined – unless you need to get an additional logic & info in more-info) – could be an icon of a device / vehicle / person / pet / ...:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      label_mode: icon
      icon: mdi:car
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.my_truck
      label_mode: icon
      icon: mdi:truck

Show an icon for an entity with entity_picture - instead of that picture:

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.phone
      label_mode: icon
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.phone
cluster: true

And the icon can be customized:

      - entity: device_tracker.demo_anne_therese
        badge:
          entity: sensor.phone
          label_mode: icon
          icon: mdi:cellphone-basic

Show an image (entity may be NOT defined – unless you need to get an additional logic & info in more-info) – could be an image of a device / vehicle / person / pet / ...:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      label_mode: image
      image: /local/images/test/iphone_5s.png
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.another_phone
      label_mode: image
      image: /local/images/test/iphone_5s.png

Show a state (with or w/o a unit) – could be a battery_level / speed / ...:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      entity: sensor.battery_1
      label_mode: state
  - entity: device_tracker.demo_home_boy
    badge:
      entity: sensor.battery_2
      label_mode: state
      hide_unit: true

Show an attribute (with or w/o a unit) (just a synthetic example, could be anything else of course):

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: climate.ecobee
      label_mode: attribute
      attribute: current_temperature
  - entity: device_tracker.demo_paulus
    badge:
      entity: climate.ecobee
      label_mode: attribute
      attribute: current_temperature
      hide_unit: true

Example for geo_location sources:

type: map
geo_location_sources:
  - source: gdacs
    label_mode: attribute
    attribute: event_type
    badge:
      label_mode: attribute
      attribute: alert_level

With state_color set:

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sensor.battery_1
      state_color: true

With color set to colorize an icon & a label:

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      icon: mdi:car
      color: red
  - entity: device_tracker.demo_paulus
    badge:
      label_mode: label
      label: 123
      color: magenta

With background_color defined:

type: map
entities:
  - entity: device_tracker.demo_anne_therese
    badge:
      entity: sun.sun
      background_color: orange
  - entity: device_tracker.demo_paulus
    badge:
      entity: sensor.carbon_dioxide
      label_mode: state
      background_color: orange
  - entity: device_tracker.demo_home_boy
    badge:
      label_mode: image
      image: /local/images/test/iphone_5s.png
      background_color: orange

A wrong config causes an mdi:alert:

type: map
entities:
  - entity: device_tracker.demo_paulus
    badge:
      entity: sun.sun
      label_mode: attribute

Screenshots

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New feature (thank you!)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue or discussion:
Link to documentation pull request:
Link to developer documentation pull request:
Link to backend pull request:

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

MindFreeze · 2026-04-07T05:40:40Z

src/components/map/ha-map-marker-badge.ts

+          "--color": !this.badge.state_color ? this.badge.color : undefined,
+          "--background-color": this.badge.background_color,
+          "background-image": clsImageOnly
+            ? `url(${this.hass.hassUrl(this.badge.image)})`


This could be a CSS injection risk. ha-entity-marker.ts already does this so may not be a real problem though. Have to think about it

State-badge uses same this.hass.hassUrl() thing... Imho the risk should be minimized in the hassUrl function.

piitaya · 2026-04-07T08:37:47Z

How does it looks without zoom? All the screenshot are zoomed. Can you put a full map screenshot so we can have a global overview on this PR?

ildar170975 · 2026-04-07T16:00:05Z

How does it looks without zoom? All the screenshot are zoomed. Can you put a full map screenshot so we can have a global overview on this PR?

Left - with customized --ha-marker-size: 64px, right - with default 48px:

The bigger variant looks more-or-less OK on iPhone 15. (update: I would say - "OK", not just "more-or-less OK")
The smaller variant looks OK on iPad Air 2 - and looks fine on a wall-mounted 4K screen.

But the "icon badge" is not a big issue.
The "label badge" with some state/attribute is looking OK only on a large screen, not for iPhone.
That is why we need to add conditions for badges - including mediaquery ones. Then we will be able to see badges on large screens & hide them on phones. People have more & more large wall-mounted screens, let's use them for these thingies))

ildar170975 · 2026-04-07T20:00:36Z

First renamed label_mode -> display_mode, did not like the naming...
But then recalled that I named the option like a similar option for a map entity, and then reverted back to label_mode...

wendevlin · 2026-04-08T10:12:52Z

Hi @ildar170975,

We discussed this and will close it because:

The purpose of the Map is to show where is smth. It's not to show a state of smth, like battery or text.
- if you need the state there are way better cards like the tile card.
As we see in your zoomed out screenshots it's way too tiny to have actual a value.

Sorry and thanks for the proposal!
Maybe you could think of designing your own custom map card with this feature enabled if you want to use it for yourself?

Best
Wendelin

ildar170975 · 2026-04-08T10:54:37Z

The purpose of the Map is to show where is smth. It's not to show a state of smth, like battery or text.

We already have a “label_mode” feature for map markers to show info - then what is a big deal with showing additional info in additional badges?
I see no logic in your decision. Just a hasty rejection.

wendevlin · 2026-04-08T11:03:24Z

I see no logic in your decision. Just a hasty rejection.

I am sorry that you feel like that. But it's not true. As I said to you we discussed it. So we as a group of 5 people looked into your PR and decided that this badge doesn't add additional value to the marker and it's way too small.

ildar170975 · 2026-04-08T11:10:17Z

Not so small for a big screen. And you can always increase the marker (and a badge) with a theme variable. And there will be media query conditions as was described.
Of course I will implement this in an already made custom map card. And this custom card will be used more by people who prefer additional features. Honestly see no thorough thinking in your decision, sorry.

As for additional info. There is such a thing like “secondary info”. Here the badge is same. Why do we have additional secondary info? Let’s propose users not have it.
Secondary info adds a value - it adds more information. Badge adds more information. Obvious things.

wendevlin · 2026-04-08T11:45:34Z

Thanks for the additional context and for sharing your perspective. We understand your reasoning and appreciate the effort you put into this PR. Our decision stands, but we wish you all the best with your custom card!

ildar170975 added 6 commits April 7, 2026 05:28

add MapMarkerBadgeConfig

a994cb2

add badge

d13ec4f

Create ha-map-marker-badge.ts

28e7086

add map marker badges

2a84ef2

add map marker badges

9a7394b

add map marker badge

6130de7

home-assistant bot added the cla-signed label Apr 7, 2026

ildar170975 added 3 commits April 7, 2026 06:21

prettier

a96b635

prettier

223894b

prettier

ad724f6

ildar170975 marked this pull request as ready for review April 7, 2026 03:36

MindFreeze reviewed Apr 7, 2026

View reviewed changes

ildar170975 added 5 commits April 7, 2026 19:10

Merge branch 'dev' into map-marker-badge

8f93109

resolving conflicts

0ae7ae8

label_mode -> display_mode

66349d6

prettier

cef74b3

revert: display_mode -> label_mode

1a6c7c3

update mapBadgeConfigStruct

9be11b7

wendevlin closed this Apr 8, 2026

ildar170975 deleted the map-marker-badge branch April 8, 2026 12:44

ildar170975 mentioned this pull request Apr 9, 2026

feat: Map marker badges nathan-gs/ha-map-card#196

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Map: add marker badges#51435

Map: add marker badges#51435
ildar170975 wants to merge 15 commits intohome-assistant:devfrom
ildar170975:map-marker-badge

ildar170975 commented Apr 7, 2026 •

edited

Loading

Uh oh!

MindFreeze Apr 7, 2026

Uh oh!

ildar170975 Apr 7, 2026

Uh oh!

piitaya commented Apr 7, 2026

Uh oh!

ildar170975 commented Apr 7, 2026 •

edited

Loading

Uh oh!

ildar170975 commented Apr 7, 2026

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

ildar170975 commented Apr 8, 2026

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

ildar170975 commented Apr 8, 2026 •

edited

Loading

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ildar170975 commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking change

Proposed change

Screenshots

Type of change

Additional information

Checklist

Uh oh!

MindFreeze Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

ildar170975 Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

piitaya commented Apr 7, 2026

Uh oh!

ildar170975 commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ildar170975 commented Apr 7, 2026

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

ildar170975 commented Apr 8, 2026

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

ildar170975 commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wendevlin commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ildar170975 commented Apr 7, 2026 •

edited

Loading

ildar170975 commented Apr 7, 2026 •

edited

Loading

ildar170975 commented Apr 8, 2026 •

edited

Loading