mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-12-10 00:30:02 -06:00
215 lines
8.8 KiB
Markdown
215 lines
8.8 KiB
Markdown
---
|
|
type: card
|
|
title: "Map card"
|
|
sidebar_label: Map
|
|
description: "The map card that allows you to display entities on a map"
|
|
related:
|
|
- docs: /dashboards/dashboards/#map-dashboard
|
|
title: Map dashboard
|
|
- docs: /integrations/frontend/
|
|
title: Themes
|
|
- docs: /dashboards/cards/
|
|
title: Dashboard cards
|
|
- docs: /docs/configuration/basic/#editing-the-general-settings
|
|
title: Edit your home location
|
|
- docs: /getting-started/presence-detection/
|
|
title: 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](/dashboards/dashboards/#map-dashboard), which is one of the default dashboards.
|
|
|
|
<p class='img'>
|
|
<img src='/images/dashboards/map_card.webp' alt='Screenshot of the map card'>
|
|
Screenshot of the map card.
|
|
</p>
|
|
|
|
## 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](/dashboards/cards/#adding-cards-to-your-dashboard) to your dashboard.
|
|
3. By default, you see the house {% icon "mdi:house" %} icon on your map. It represents your [home zone](/integrations/zone/#about-the-home-zone).
|
|
- To change the location of your home, you need to [edit your home's location in the general settings](/docs/configuration/basic/#editing-the-general-settings).
|
|
|
|
|
|
4. To learn how to show additional zones on your map, follow the steps on [adding a new zone](/integrations/zone/#adding-a-new-zone-or-editing-zones).
|
|
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](#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](/getting-started/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](#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](#options-for-entities)). 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](#options-for-geolocation-sources)). All current entities with that source will be displayed on the map. See [Geolocation](/integrations/geo_location/) 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
|
|
cluster:
|
|
required: false
|
|
description: 'When set to `false`, the map will not cluster the markers. This is useful when you want to see all markers at once, but it may cause performance issues with a large number of markers.'
|
|
type: boolean
|
|
default: true
|
|
{% 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](/integrations/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
|
|
unit:
|
|
required: false
|
|
description: A unit 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](/integrations/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
|
|
unit:
|
|
required: false
|
|
description: A unit 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
|
|
|
|
```yaml
|
|
type: map
|
|
aspect_ratio: 16:9
|
|
default_zoom: 8
|
|
auto_fit: true
|
|
entities:
|
|
- device_tracker.demo_paulus
|
|
- zone.home
|
|
```
|
|
|
|
```yaml
|
|
type: map
|
|
geo_location_sources:
|
|
- nsw_rural_fire_service_feed
|
|
- source: gdacs
|
|
focus: false
|
|
entities:
|
|
- zone.home
|
|
```
|
|
|
|
```yaml
|
|
type: map
|
|
entities:
|
|
- device_tracker.demo_paulus
|
|
- entity: sensor.gas_station_gas_price
|
|
label_mode: state
|
|
focus: false
|
|
hours_to_show: 48
|
|
```
|