Map card
The map card can show your home zone, your other zones, and entities with a location on a map. This card is used on the Map dashboard, which is one of the default dashboards.
The Map dashboard, with the map card in a panel view and the People tab open.
On the map, each entity is shown as a marker that floats above its location. The marker shows the entity’s picture or, if it doesn’t have one, its initials. Instead, you can let it show the entity’s icon, name, state, or an attribute. Entities that report how accurate their location is, such as a phone, also show a circle of that size in their color. When you zoom out far enough, the map turns into a globe.
Below the zoom buttons, two more buttons help you find your way on the map:
-
Toggle grouping
combines markers that are close together into one bubble. The bubble shows up to four markers. For larger groups, it shows three markers and the number of remaining markers. People in the same zone share one bubble above the icon of that zone. Select a bubble to zoom in until its markers separate. If the markers are at the same spot, the bubble opens and shows each marker. Select the button again to show each marker separately. While markers are not grouped, the button shows . The button is only shown when there is more than one marker. -
Reset focus
moves and zooms the map so that you can see your entities again. Entities with Focus turned off are left out, and zones are only included if Fit zones is turned on. If Auto fit is turned on, the map also starts following your entities again.
People, devices, and zones in a panel view
When the map card is in a panel view, such as on the Map dashboard, it also shows the People, Devices, and Zones tabs on top of the map, if the card shows at least one person, device, or zone. A tab is only shown if it has something to list. On a phone, the tabs are in a sheet at the bottom of the screen. Drag the sheet up or down to show more or less of the list. The tabs show the following:
- People: the people in your home and where they are. You are listed first, as Me. People without a location are listed too, but dimmed.
- Devices: the devices on the map that have a location. A device that belongs to a person is shown as that person, not as a separate device.
- Zones: your zones, with the number of people in each zone. Your home zone is listed first.
People and devices are only shown on the map while their tab is selected. Zones and other entities with a location are always shown. The circle that marks the size of a zone is only drawn on the Zones tab, for the selected zone, or when Show zone radius is turned on. Passive zones are not shown in a panel view.
Select an item in the list or on the map to see its details. The map moves to the item, and only zooms in as far as needed to separate it from nearby markers. The selected marker is larger and shows the circle of its location accuracy. The details show the Activity of the item from the last 24 hours:
- For a person or a device, the activity shows its changes, such as arriving at or leaving a zone.
- For a zone, the activity shows the people who arrived or left.
The activity shows the five most recent entries. To see up to twenty, select Show more. The activity uses the History integration.
To open the more-info dialog of the item, select More info. To go back to the list, select Back
Adding the map card to a dashboard
- In the top right of the screen, select Edit dashboard
. - 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.
- Once you’ve taken control, you can’t set this dashboard to update automatically anymore. However, you can create a new default dashboard.
- To continue, in the dialog, select Menu
, then select Take control.
- If this is your first time editing a dashboard, the Edit dashboard dialog appears.
-
Add the map card to your dashboard.
- If the card is in a sections view, you can resize it on the Layout tab. In other view types, the Layout tab is not shown. For more information, refer to resizing a card.
- By default, you see the house
icon on your map. It represents your home zone. - To change the location of your home, you need to edit your home’s location in the home information.
- To learn how to show additional zones on your map, follow the steps on adding a new zone.
- To show other elements on the map, add entities or geolocation sources:
- To add an entity, under Entities, select Add entity. The list shows only entities that have a location, such as a phone with the Home Assistant Companion app.
- To add a geolocation source, under Geolocation sources, select Source.
- For more information about presence detection, refer to the getting started tutorial on presence detection.
- Optional: To change how the map looks, expand Appearance. For example, select a Map style or a Theme mode.
- To see a trace of the past locations of your entities, enter the number of hours under Hours to show.
- For a description of all settings, refer to Card settings.
- Select Save.
Card settings
The settings are listed in the order in which they appear in the card editor. For more details about a setting, refer to its YAML option in the YAML configuration section.
Expand this section to change how the map looks.
The look of the map: Default, Colorful, Natural, Muted, Gray, or Toner (map_style). Each style has a light and a dark version. The Theme mode decides which version is shown. On devices that can’t show the detailed map, such as some older tablets, a simpler map is shown, and the map style has no effect. To adjust a style further, for example its colors, use YAML. For more information, refer to options for a custom map style.
Shows the path of the previous locations of your entities for the given number of hours (hours_to_show).
Moves and zooms the map each time your entities change location, so that you can always see all of them (auto_fit). When you move or zoom the map yourself, the map stops following your entities until you select Reset focus.
Also keeps the zones in your list of entities in view when the map moves and zooms to show your entities, unless their Focus is turned off (fit_zones).
In a panel view, always draws the circle that marks the size of each zone, not only on the Zones tab (show_zone_radius).
Automatically adds all entities with a location to the map (show_all). If you turn this on, remove the entities and geolocation sources you added, because they can’t be combined with Show all.
The entities to show on the map (entities). To add an entity, select Add entity. To change the settings of an entity, select Edit
The color of the marker and of the path of previous locations (color). Select one of the theme colors, or enter a hex color code, for example, #93c47d, and select Custom color. Not available for zones.
What the marker shows: Name, State, Attribute, or Icon (label_mode). Not available for zones.
The attribute to show when Label mode is set to Attribute (attribute). Not available for zones.
The geolocation sources whose entities you want to show (geo_location_sources). To add a source, select Source, then select the source.
Shows the entities only when all conditions are met (conditions). For more information, refer to conditions options.
YAML configuration
The following YAML options are available when you use YAML mode or prefer to use YAML in the code editor in the UI.
Configuration Variables
List of entity IDs or entities with their own settings. For more information, refer to options for entities. Either this, show_all, or the geo_location_sources configuration option is required.
List of geolocation sources or sources with their own settings. For more information, refer to options for geolocation sources. Shows all current entities of these sources. For valid sources, refer to integrations that provide geolocation entities. To show all available sources, add all to the list. Either this, show_all, or the entities configuration option is required.
Automatically adds all entities with a location to the map. The Map dashboard uses this setting. Can’t be combined with entities or geo_location_sources. If you use one of them together with show_all, the card shows an error.
Moves and zooms the map each time your entities change location, so that you can always see them. Entities with focus: false are left out. When you move or zoom the map yourself, the map stops following your entities until you select Reset focus.
Also keeps the zones in your list of entities in view when the map moves and zooms to show your entities, unless they have focus: false.
In a panel view, the circle that marks the size of a zone is only drawn on the Zones tab and for the selected zone. When set to true, the circle of every zone is always drawn. In other views, the circles are always drawn and this option has no effect.
Sets the height of the map compared to its width. Use a percentage of the width (23%) or a ratio with a colon or an “x” (16:9 or 16x9). If you leave out the second number of a ratio, it is 1 (1.78 equals 1.78:1).
The zoom level of the map when it opens. Use a lower number to zoom out and a higher number to zoom in. When the map moves and zooms to show your entities, it never zooms in further than this level.
Shows a ruler that indicates the current scale of the map.
Shows the map in light mode (light), dark mode (dark), or following your theme (auto). The theme mode also decides whether the light or the dark version of the map_style is shown.
The style of the map: default, colorful, natural, muted, gray, or toner. To adjust a style, use a map instead of a style name. For more information, refer to options for a custom map style. On devices that can’t show the detailed map, such as some older tablets, a simpler map is shown, and map_style has no effect.
Shows the path of the previous locations of your entities for the given number of hours. Point at a spot on a path to see the name and the time. The paths use the History integration.
When set to false, markers that are close together are not combined into one bubble. This is useful when you want to see all markers at once. With a large number of markers, the map can respond more slowly.
List of conditions to check for entity visibility. For more information, refer to conditions options.
Only entities that have a location, with latitude and longitude attributes, are shown on the map. People are the exception: a person without a location is shown in the zone they are in, for example, at home.
Conditions options
With conditions, each entity is only shown when it meets all conditions. For the available conditions, refer to conditions options of the conditional card. In conditions that use an entity, the entity ID is filled in automatically with each entity on the map.
Example
The following example shows all entities with a location, except the ones whose state is home.
type: map
auto_fit: true
show_all: true
conditions:
- condition: state
state_not: home
Options for a custom map style
If you define map_style as a map instead of a style name, you can start from one of the styles and adjust it. Only the options listed here are documented. You can write the option names in snake_case or in camelCase, so settings that you copy from the VersaTiles style editor work as they are.
Configuration Variables
The style to start from: default, colorful, natural, muted, gray, or toner.
Colors for parts of the map, such as water, land, natureWood, building, or roadStreet. For all names, refer to map color names. The colors you set replace only these parts. The rest of the style stays as it is. If you don’t set colors_dark, these colors are used in both the light and the dark version of the map.
Colors for the dark version of the map. If set, the dark version uses colors_dark instead of colors. The two are not merged, so add every color you want to change on the dark map to colors_dark.
Adjustments for all colors of the style, such as saturate (from -1 for grayscale to 1 for twice the saturation), rotate_hue (in degrees), brightness, contrast, gamma, or invert_brightness. To mix a color into the whole style, use tint or blend, each with a color and an amount.
The following example starts from the Muted style, changes the color of water, and uses a darker water color on the dark version of the map.
type: map
show_all: true
map_style:
base: muted
colors:
water: "#9ec9e2"
colors_dark:
water: "#1f3a5f"
Map color names
You can use the following names under colors and colors_dark:
- Land and water:
background,land,water,glacier - Nature:
natureWood,natureGrass,naturePark,natureLeisure,natureAgriculture,natureWetland,natureSand,natureRock - Areas and sites:
areaResidential,areaCommercial,areaIndustrial,areaWaste,areaBurial,siteParking,siteSports,siteConstruction,siteEducation,siteHospital,siteDanger,sitePrison - Buildings:
building,buildingBg - Roads:
roadStreet,roadStreetBg,roadTrunk,roadTrunkBg,roadMotorway,roadMotorwayBg - Transit and paths:
transitRail,transitSubway,transitCycle,transitFoot - Boundaries:
boundary,boundaryDisputed - Labels:
label,labelHalo,labelWater,labelSymbol,labelPoi,labelShield,labelHousenumber
The default colors for construction, education, hospital, danger, and prison sites are partly transparent, so the map underneath stays visible. To keep this effect, use a color with transparency, such as #FF66661A.
Names ending in Bg set the outline color of that part, for example the edge of a road.
Map colors in a theme
A theme can also change the colors of the map. Set one or more of the following variables in your theme:
- Land and water:
ha-color-map-land,ha-color-map-water,ha-color-map-green,ha-color-map-area - Buildings:
ha-color-map-building,ha-color-map-building-outline - Roads and transit:
ha-color-map-road,ha-color-map-road-major,ha-color-map-road-outline,ha-color-map-transit - Boundaries and labels:
ha-color-map-boundary,ha-color-map-label,ha-color-map-label-halo,ha-color-map-label-secondary
The theme colors are applied on top of the map style, and the colors of the card are applied on top of the theme colors. The theme colors are only used when the Theme mode of the card matches the light or dark mode of your theme.
Options for entities
To change the settings of a single entity, write it as - entity: ENTITY_ID with its settings below it, instead of only the entity ID.
Configuration Variables
The color of the marker and of the path of previous locations. Use a theme color: primary, accent, red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, light-grey, grey, dark-grey, blue-grey, black, or white. Theme colors follow your theme. You can also use a hex color code, for example, #93c47d. If not set, a color is picked for each entity. For a zone, the color is used for the zone and its marker, except for passive zones. The card editor doesn’t offer this option for zones, and it removes the color of a zone when you edit that zone in the editor.
When set to icon, the marker shows the entity’s icon instead of text. When set to state or attribute, the marker shows the entity’s state or attribute instead of the entity’s name. This option doesn’t apply to zone entities because they show an icon instead of a label.
The unit to show after the attribute value when label_mode is set to attribute.
Options for geolocation sources
To change the settings of a single geolocation source, write it as - source: SOURCE_NAME with its settings below it, instead of only the source name.
Configuration Variables
When set to icon, the marker shows the entity’s icon instead of text. When set to state or attribute, the marker shows the entity’s state or attribute instead of the entity’s name.
The unit to show after the attribute value when label_mode is set to attribute.
Examples
The following example shows a person’s phone and the home zone. The map follows the phone when it moves.
type: map
aspect_ratio: 16:9
default_zoom: 8
auto_fit: true
entities:
- device_tracker.demo_paulus
- zone.home
The following example shows the entities of two geolocation sources and the home zone. The map does not move to keep the entities of the gdacs source in view.
type: map
geo_location_sources:
- nsw_rural_fire_service_feed
- source: gdacs
focus: false
entities:
- zone.home
The sensor.gas_station_gas_price entity in the following example is a placeholder. Replace it with an existing entity that has numeric latitude and longitude attributes.
type: map
entities:
- device_tracker.demo_paulus
- entity: sensor.gas_station_gas_price
label_mode: state
focus: false
hours_to_show: 48