# Map of KPIs Widget type: `kpi-map` · Plugin: `@opendash/plugin-mobility` ![Map of KPIs preview](../../../../../_attachments/opendash/widgets/assets/widget-previews/kpi-map.png) ## Description Plots KPI data points on a map with adjustable positions. Useful for spatial distribution of indicators and interactive inspection. The widget renders a MapLibre/Mapbox map on which you can freely place markers, drag them to a position, and have each marker display a static text label, a link to another dashboard, or the current value of a selected data dimension. Optional geographic zones (districts) can be overlaid as colored areas, and clustered geo data dimensions are shown as interactive points/lines/polygons that expand on click. ## Data requirements - Data selection: by dimension (`select: "dimension"`), minimum 0 items (data is optional — `dataOptional: true`). Allowed value type: `Geo`. - Data fetching: live and history are both supported. - The widget can be used without any data items selected (markers and zones alone are sufficient). When geo dimensions are supplied, their features are clustered and drawn on the map. ## Options | Option | Type | Default | Description | | --- | --- | --- | --- | | `markers` | `KPiMapMarker[]` | `[]` | List of markers placed on the map. Markers are created/edited interactively in edit mode (unlocked via the lock button) rather than in the settings panel. Each marker has `latitude`, `longitude`, `type` (`"text"`, `"dashboard"`, or `"data-dimension"`), `label`, `fontSize`, `rotation`, `border` (`"solid"` / `"semi"` / `"none"`), `initialZoom`, and optional `icon`. A `dashboard` marker also stores `source` and `dashboardid`; a `data-dimension` marker stores `data` (a data item dimension reference); a `text` marker stores a `subtitle`. | | `zones` | `GeograhpySelectionType` | `{ type: "zones", districtsFromZones: [], districts: null, districtFromDimension: null }` | Geographic zones overlaid as colored areas. Configured in the settings panel via the geography selector with three sources: From Datasource (a geo data dimension), From Zones (a selection of predefined zones), or External Source (a GeoJSON/ESRI shape string). | | `hideEditButton` | `boolean` (optional) | `—` | When `true`, hides the lock/unlock edit button so end users cannot enter marker edit mode. | Marker edit dialog (shown in edit mode) lets you set the marker type ("Label", "Dashboard", "Dimension"), pick a target dashboard or data dimension, set the name, icon, font scale, rotation, and background style. ## Presets - Map of KPIs — Plots KPI data points on a map with adjustable positions. Useful for spatial distribution of indicators and interactive inspection. Tags: `map`. Default config matches the data explorer: empty `markers` and a `zones` selection of type `zones`. ## How to use 1. Add the "Map of KPIs" widget to a dashboard (it appears under the geo/map widgets). 2. Optionally select one or more geo data dimensions; leaving the selection empty is allowed. 3. In the settings panel, configure the zones overlay if you want districts drawn: choose From Datasource, From Zones, or paste GeoJSON under External Source. 4. On the map, click the lock button (top right) to enter edit mode, then click on the map to drop a marker. 5. Click a marker to open its dialog and choose its type: a static text label, a link to another dashboard, or a live value from a data dimension. Drag markers to reposition them; the position and zoom are saved automatically. 6. Lock the map again (or set `hideEditButton`) to present a read-only KPI map to end users.