Map card

The map card that allows you to display entities on a map. This card is used on the Map dashboard, which is one of the default dashboards.

Screenshot of the map card Screenshot of the map card.

To add the map card to your user interface:

  1. In the top right of the screen, select the pencil icon.
    • If this is your first time editing a dashboard, the Edit dashboard dialog appears.
      • By editing the dashboard, you are taking over control of this dashboard.
      • This means that it is no longer automatically updated when new dashboard elements become available.
      • To continue, in the dialog, select the three dots menu, then select Take control.
  2. Add a card to your dashboard.

All options for this card can be configured via the user interface.

YAML configuration

The following YAML options are available when you use YAML mode or just prefer to use YAML in the code editor in the UI.

Configuration Variables

type string Required


entities list Required

List of entity IDs or entity objects (see below). Either this or the geo_location_sources configuration option is required.

geo_location_sources list Required

List of geolocation sources. All current entities with that source will be displayed on the map. See Geolocation platform for valid sources. Set to all to use all available sources. Either this or the entities configuration option is required.

auto_fit boolean (Optional, default: false)

The map will follow moving entities by adjusting the viewport of the map each time an entity is updated.

fit_zones boolean (Optional, default: false)

Whether the map should consider the zones in the list of specified entities when fitting its viewport.

title string (Optional)

The card title.

aspect_ratio string (Optional)

Forces the height of the image to be a ratio of the width. Valid formats: Height percentage value (23%) or ratio expressed with colon or “x” separator (16:9 or 16x9). For a ratio, the second element can be omitted and will default to “1” (1.78 equals 1.78:1).

default_zoom integer (Optional)

The default zoom level of the map.


14 (or whatever zoom level is required to fit all visible markers)

theme_mode string (Optional, default: auto)

Override the theme to force the map to display in either a light mode (theme_mode: light) or a dark mode (theme_mode: dark). Default (theme_mode: auto) will follow the theme settings.

hours_to_show integer (Optional, default: 0)

Shows a path of previous locations. Hours to show as path on the map.


Only entities that have latitude and longitude attributes will be displayed on the map.


The default_zoom value will be ignored if it is set higher than the current zoom level after fitting all visible entity markers in the map window. In other words, this can only be used to zoom the map out by default.

Options for entities

If you define entities as objects instead of strings (by adding entity: before entity ID), you can add more customization and configuration.

Configuration Variables

entity string Required

Entity ID.

name string (Optional)

Replace the default label for the marker.

label_mode string (Optional, default: name)

When set to state, renders the entity’s state as the label for the map marker instead of the entity’s name. This option doesn’t apply to zone entities because they don’t use a label but an icon.

focus boolean (Optional, default: true)

When set to false, this entity will not be considered for determining the default zoom or fit of the map.


type: map
aspect_ratio: 16:9
default_zoom: 8
auto_fit: true
  - device_tracker.demo_paulus
  - zone.home
type: map
  - nsw_rural_fire_service_feed
  - zone.home
type: map
  - device_tracker.demo_paulus
  - entity: sensor.gas_station_gas_price
    label_mode: state
    focus: false
hours_to_show: 48