Skip to content

Latest commit

 

History

History
217 lines (195 loc) · 8.86 KB

map.markdown

File metadata and controls

217 lines (195 loc) · 8.86 KB
type title sidebar_label description related
card
Map card
Map
The map card that allows you to display entities on a map
docs title
/dashboards/dashboards/#map-dashboard
Map dashboard
docs title
/integrations/frontend/
Themes
docs title
/dashboards/cards/
Dashboard cards
docs title
/docs/configuration/basic/#editing-the-general-settings
Edit your home location
docs title
/getting-started/presence-detection/
Getting started tutorial on presence detection

The map card allows you to display your home zone, entities, and other predefined zones 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.

Adding the map card to your dashboard

  1. In the top right of the screen, select the edit {% icon "mdi:edit" %} button.

    • 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 the three dots {% icon "mdi:dots-vertical" %} menu, then select Take control.

  2. Add the map card to your dashboard.

  3. By default, you see the house {% icon "mdi:house" %} icon on your map. It represents your home zone.

    Edit map card settings

  4. To learn how to show additional zones on your map, follow the steps on adding a new zone.

  5. To show other elements on the map, either add them under Entities, or use the Geolocation sources.

    • For a description of the options, refer to the YAML configuration section. It also applies to the options shown in the UI.
    • {% icon "mdi:info" %} Info: The list of entities shows the device trackers available for your home, such as a mobile phone with the companion app.
      • If you want to see a trace of the past locations of your entities, you need to define a time frame under Hours to show.
    • For more information about presence detection, refer to the getting started tutorial on presence detection.

Configuration options

All options for this card can be configured via the user interface. For a detailed description of the options, refer to the YAML configuration section. It also applies to the options shown in the UI.

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 %} type: required: true description: "map" type: string entities: required: false description: List of entity IDs or entity objects (see below). Either this, show_all, or the geo_location_sources configuration option is required. type: list geo_location_sources: required: false description: List of geolocation sources or source objects (see below). 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, show_all, or the entities configuration option is required. type: list show_all: required: false description: Automatically add all entities with coordinates to the map card. (Default behavior of Map panel) type: boolean default: false auto_fit: required: false description: The map will follow moving entities by adjusting the viewport of the map each time an entity is updated. type: boolean default: false fit_zones: required: false description: Whether the map should consider the zones in the list of specified entities when fitting its viewport. type: boolean default: false title: required: false description: The card title. type: string aspect_ratio: required: false description: '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).' type: string default_zoom: required: false description: The default zoom level of the map. Use a lower number to zoom out and a higher number to zoom in. type: integer default: 14 (or whatever zoom level is required to fit all visible markers) theme_mode: required: false description: '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.' type: string default: 'auto' hours_to_show: required: false description: Shows a path of previous locations. Hours to show as path on the map. type: integer default: 0 {% endconfiguration %}

{% important %} Only entities that have latitude and longitude attributes will be displayed on the map. {% endimportant %}

{% note %} 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. {% endnote %}

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 %} entity: required: true description: Entity ID. type: string name: required: false description: Replace the default label for the marker. type: string label_mode: required: false default: name description: When set to icon, renders the entity's icon in the marker instead of text. When set to state or attribute, renders the entity's state or attribute 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. type: string attribute: required: false description: An entity's attribute when label_mode set to attribute. type: string prefix: required: false description: A prefix for a value of an attribute when label_mode set to attribute. type: string suffix: required: false description: A suffix for a value of an attribute when label_mode set to attribute. type: string focus: required: false default: true description: When set to false, this entity will not be considered for determining the default zoom or fit of the map. type: boolean {% endconfiguration %}

Options for geolocation sources:

If you define geolocation sources as objects instead of strings (by adding source: before the ID), you can add more customization and configuration.

{% configuration %} source: required: true description: Name of a geolocation source, or all. type: string label_mode: required: false default: name description: When set to icon, renders the entity's icon in the marker instead of text. When set to state or attribute, renders the entity's state or attribute 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. type: string attribute: required: false description: An entity's attribute when label_mode set to attribute. type: string prefix: required: false description: A prefix for a value of an attribute when label_mode set to attribute. type: string suffix: required: false description: A suffix for a value of an attribute when label_mode set to attribute. type: string focus: required: false default: true description: When set to false, the entities of this source will not be considered for determining the default zoom or fit of the map. type: boolean {% endconfiguration %}

Examples

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