Map spark

The map spark adds advanced map state management to a map card used inside a UIX Forge forged element. It supports three modes:

• Memory mode (memory: true): Captures the current Leaflet zoom and centre before each update and restores them afterwards, so the user's view is always preserved. Without it, every forge template update causes the map to reset to its default zoom level and centre position.
• Fit map mode (fit_map: true): Fits the map view when map card does not auto fit on load when used in custom cards which may hide the map initially. e.g. custom: auto-entities.
• Tour mode (tour: true | object): Automatically moves the map between a list of points of interest. A pause/play button is injected into the map. When tour: true all defaults are used; pass an object to customise behaviour.

Basic usage

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      memory: true
element:
  type: map
  entities:
    - device_tracker.phone

Configuration

Tour sub-keys

Each poi list entry may contain:

Tour CSS variables

The pause/play button can be styled using CSS variables placed on the ha-card or any ancestor:

How it works

Memory mode:

Each time the forged element is about to refresh due to a forge template update, the spark:

1. Reads the current zoom and center from the Leaflet map instance inside ha-map.
2. Waits for the forged element and then ha-map to finish their own update cycle.
3. Calls leafletMap.setView(center, zoom, { reset: true }) to silently restore the saved position without triggering an animation.

If Leaflet has not yet initialised when the refresh fires (e.g. on initial render) the save step is skipped and no restore is attempted, so the map displays its default view on first load.

Fit map mode:

After the forged element and ha-map finish updating and once ha-map client width is non-zero and leaflet is ready, the spark will call fitMap() on ha-map.

Tour mode:

After the map is ready (and after fit_map completes if both are configured), the spark:

1. Resolves the POI list (from poi config, or by reading latitude/longitude from hass state attributes of the ha-map entities).
2. Injects a ha-icon-button overlay into the Leaflet container with a circular SVG countdown ring around it.
3. Moves the map to the first POI immediately, then starts a repeating timer that calls leafletMap.setView() to advance to the next POI every period seconds.
4. The countdown ring animates from full to empty over each period, giving a visual indication of time remaining at the current POI.
5. When the user clicks the pause/play button, the timer is stopped or restarted and the countdown ring is hidden or restarted.

When memory: true and tour are both active, hass-update memory restores are suppressed while the tour is playing so that the tour animation is not interrupted.

Examples

Using fit map mode with auto-entities

When using a map card with custom:auto-entities the way auto-entities hides the map card will mean it does not fit on load. Fit map mode can be used in this case to make sure the map fits on first load.

No include filters have been used for brevity of the example.

type: custom:auto-entities
entities:
  - zone.home
filter:
  include: []
  exclude: []
card:
  type: custom:uix-forge
  forge:
    mold: card
    sparks:
      - type: map
        fit_map: true
  element:
    type: map
    fit_zones: true
    uix:
      style: |
        :host {
          display: block;
          height: 400px;
        }

Tour mode with default settings

Automatically cycle through all map entities using defaults (10 s per stop, pause/play button in bottom-right corner):

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      tour: true
element:
  type: map
  entities:
    - device_tracker.phone
    - device_tracker.tablet

Tour mode with custom POI list

Fly between fixed coordinates and specific entities with individual zoom levels:

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      tour:
        period: 15s
        zoom: 13
        icon_pause: mdi:pause-circle
        icon_play: mdi:play-circle
        icon_position:
          bottom: 16px
          left: 16px
        poi:
          - entity: device_tracker.phone
          - latitude: 48.8566
            longitude: 2.3522
            zoom: 11
          - entity: device_tracker.tablet
            zoom: 15
element:
  type: map
  entities:
    - device_tracker.phone
    - device_tracker.tablet

Styling the tour button

Override the default pill shape with rounded corners and a dark background:

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      tour: true
element:
  type: map
  entities:
    - device_tracker.phone
  uix:
    style: |
      ha-card {
        --uix-map-tour-icon-color: white;
        --uix-map-tour-icon-background: rgba(0,0,0,0.5);
        --uix-map-tour-icon-border-radius: 4px;
      }