Map spark

The map spark adds advanced map state management to a map card used inside a UIX Forge forged element. It supports five 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.
• Hours to show slider mode (hours_to_show: true | object): Injects an interactive ha-slider overlay into the map allowing users to adjust the hours of history loaded and rendered in real-time.
• Entity filter overlay mode (entity_filter: true | object): Injects an interactive checkable dropdown checklist overlay into the map allowing users to toggle visible entities on the map in real-time.

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:

Hours to Show sub-keys

Entity Filter sub-keys

Entity filter group sub-keys

Tour CSS variables

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

Hours to Show CSS variables

The history duration slider can be styled using CSS variables placed on the ha-card or any ancestor:

Entity Filter CSS variables

The entity filter dropdown 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.

Hours to show slider mode:

When active, the spark:

1. Renders a horizontal ha-slider control in a capsule-shaped overlay container.
2. If tour is also active and at the default position, the slider is automatically shifted leftwards to prevent visual overlapping.
3. Automatically sets, clamps, and updates hui-map-card _config.hours_to_show based on slider drags and releases to fetch history records in real-time.
4. Smoothly preserves the user's selected value across template-driven forge re-renders.

Entity filter overlay mode:

When active, the spark:

1. Renders a dropdown overlay using ha-dropdown with a trigger ha-button.
2. Resolves and displays each map entity as a checkbox using Friendly Name.
3. Directly filters visible entities. As a map card will error with no entities, deselecting any last selected entity is disabled.
4. If the show_all: true is set in forged map card config, a Show All option will also show in the dropdown. While entities are filtered, any new map entities will not show until Show All is selected.
5. If touror hours_to_show is also active and at the default position, the slider is automatically shifted leftwards to prevent visual overlapping.
6. If tour is also active, changing filtered entities will cause the map tour to restart.

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;
      }

Hours to show history slider

Enable a customizable history duration slider to load between 0 (shows all points) and 48 hours of tracker data on the map:

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      hours_to_show:
        min: 0
        max: 48
        step: 2
        position:
          bottom: 15px
          left: 15px
element:
  type: map
  entities:
    - device_tracker.phone

Entity selection filter dropdown

Enable an interactive dropdown to toggle entity tracks visibility in real-time:

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

Customise the trigger button text, size, color and icon styling:

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      entity_filter:
        label: "Trackers"
        icon: "mdi:account-multiple"
        size: "m"
        variant: "brand"
        appearance: "filled"
element:
  type: map
  entities:
    - device_tracker.phone
    - device_tracker.tablet

Display entity filter grouped by domain with custom labels

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: map
      entity_filter:
        group:
          persons: Household
          trackers: Phones
          zones: Places
element:
  type: map
  show_all: true