Home Assistant Map Card

Take a look at the blog post introducing the custom:map-card for Home Assistant.

Installation

Manual

Copy map-card.js to your /var/lib/hass/www folder.
Click on Edit Dashboard, Manage resources add /local/map-card.js as JavaScript Module.

HACS

TIP

The PR to add this to the default HACS repo is still open: hacs/default#2377

Follow the instructions to add a HACS Custom Repository.

Usage

TIP

Home Assistant contains a native map feature, if you don't need advanced features like WMS layers it might be a better choice.

Minimal

type: custom:map-card
x: 51.23
y: 3.652

More advanced

TIP

Take a look at: https://nathan.gs/2024/01/06/ha-map-card-a-new-and-alternative-leaflet-based-map/#a-more-advanced-example-measuring-pm25-air-quality-for-my-home

Options

name	Default	note
`x`		Longitude
`y`		Latitude
`history_start`		Date: `2022-03-01T12:00:00Z` Time code: `5 hours ago` Entity: `input_number.example_number` See History options for full details.
`history_end`	`now`	Date: `2022-03-01T12:00:00Z` Time code: `5 hours ago` Entity: `input_number.example_number` See History options for full details.
`focus_entity`		Entity to focus on. Map will default to show all markers if this and X/Y are not set.
`title`		If empty, don't show a title
`zoom`	12	The zoom level. Ignored unless focus_entity or X & Y coords are set.
`card_size`	5	The Home Assistant card size
`entities`	[]	Array of entities, will be listed as markers
`wms`	[]	WMS Layers, an array of `WMS` see below
`tile_layers`	[]	Tile Layers, an array of `Tile Layers` see below
`tile_layer_url`	https://tile.openstreetmap.org/{z}/{x}/{y}.png	Override the default map source
`tile_layer_attribution`	© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>	Set the correct map attribution
`tile_layer_options`	{}	The `options` for the default TileLayer
`history_date_selection`	false	Will link with a `energy-date-selection` on the page to provide an interactive date range picker.
`theme_mode`	auto	`auto`, `light` or`dark`
`debug`	false	Enable debug messages in console.

If x & y or focus_entity is not set it will take the lat/long from the first entity.

Entity options

Either the name of the entity or:

name	Default	note
`entity`		The entity id
`display`	`marker`	`icon`, `state` or `marker`. `marker` will display the picture if available
`picture`		Set a custom picture to use on the marker.
`size`	48	Size of the icon
`color`	Random Color	Can defined as `red`, `rgb(255,0,0)`, `rgba(255,0,0,0.1)`, `#ff0000`, `var(--red-color)`
`css`	`text-align: center; font-size: 60%;`	CSS for the marker (only for `state` and `marker`)
`history_start`		Will inherit from map config if not set. Date: `2022-03-01T12:00:00Z` Time code: `5 hours ago` Entity: `input_number.example_number` See History options for full details.
`history_end`	`now`	Will inherit from map config if not set. Date: `2022-03-01T12:00:00Z` Time code: `5 hours ago` Entity: `input_number.example_number` See History options for full details.
`history_line_color`	Random Color	Can defined as `red`, `rgb(255,0,0)`, `rgba(255,0,0,0.1)`, `#ff0000`, `var(--red-color)`
`history_show_lines`	true	Show the path
`history_show_dots`	true	Show little dots on the path
`fixed_x`		Display a fixed marker, this will ignore the latitude/longitude attributes
`fixed_y`		Display a fixed marker, this will ignore the latitude/longitude attributes
`fallback_x`		If the latitude/longitude is missing, use these fixed attributes
`fallback_y`		If the latitude/longitude is missing, use these fixed attributes
`tap_action`	{"action": "more-info"}	Allow custom action to be triggered when this entity is clicked. Actions include `more-info`, `call-service`, `navigate`, `url`, `assist`, `none`. Some actions require additional paramaters. `navigate` requires a `navigation_path`. `url` requires a `url_path`. `call-service` requires `service` and an optional `data`
`gradual_opacity`		The total amount of opacity will be gradually distributed across the paths. `gradual_opacity` is divided by the number of paths to calculate the opacity step for each path. The base opacity is generated by (1 - `gradualOpacity`), and as each path progresses, its opacity gradually darkens by the step amount.

History options.

If history_date_selection:true, any entities that do not define their own history_start and history_end configuration will be automatically linked to this. Please ensure a card of type: energy-date-selection exists on the page before enabling this.

This can be added via the "Add Card" dialog by selecting Manual and entering the text type: energy-date-selection.

Alternatively history_start and history_end can be set to

A specific date such as 2022-03-01T12:00:00Z
A time code such as 10 days ago 4 hours ago 1 week ago etc.
An entity that will provide either a date or number (which will be used as the amount of hours ago to show). e.g. input_number.example_number_value

If you want to specify your own unit, configure the history_start/history_end as the below.

history_start:
  entity: input_number.example_number_value
  suffix: days ago

Each entity can individually override the base config by setting its own history_start/history_end, using any of the options above. Any entity without its own settings will inherit the map level config.

WMS and tile_layers options

name	note
`url`	The url of the layer
`options`	The leaflet layer WMS options or Tile Layer options
`history`	The name of the layer option which controls the dat, if it supports a date or time option. Set history to the name of this property. The `history_start` value, state or date range picker will then set this property on the layer and update it as necessary.

Zooming & `tile_layer_options.maxZoom`

By default the map-card will not zoom beyond default property of the maxZoom of the tilelayer, the default is 18, but it can be overriden as follows:

type: custom:map-card
tile_layer_options:
  maxZoom: 20

Keep in mind that the tile layer source also has a maximum zoom level, which is 20 for most OSM maps.

Advanced WMS/Tile layer options.

More complex use of the WMS/Tile history property can be configured within the history property of the layer.

property is the option this should control (often named time or date)
source defaults to auto (which means it will inherit from the main map settings). Set this to a date or number entity if this is different.
suffix days ago/weeks ago as with other history entities
force_midnight some WMS/Tile layers only work if the date is set as midnight.

  history:
    property: time
    source: input_number.test_number_value
    suffix: months ago
    force_midnight: true

Extra Tile Layers

The leaflet-extras has a nice list of available tile layer providers.

Development

git clone git@github.com:nathan-gs/ha-map-card.git

This project uses devenv.sh.

Install devenv
devenv shell and then watch or devenv shell watch to immediatly drop into a watched shell.

NPM alternatives

npm install
npm run build (npm run watch to update on change)

Mentions & Discussions

home-assistant community: map-card: a slightly improved map-card, this topic should be used for general discussions.
nathan.gs: Map Card, a new leaflet based map with WMS and other advanced features
nathan.gs: Map Card, displaying Weather and Other Tile Layers
userbag.co.uk: Home Assistant Exploring location history
leaflet.js: third party plugins

charithmadhuranga/ha-map-card