ThingsBoard map widgets

The Map widget displays the real-time location of entities on a geographic tile map. Use it to track vehicles, sensors, assets, or any entity that reports latitude and longitude — showing current positions, coverage zones, and geographic boundaries all on one interactive map.

Map is one of four map widgets in ThingsBoard, each serving a distinct purpose:

What sets Map apart:

• Reads latitude and longitude from entity attributes or telemetry and places markers in real time.
• Supports multiple map providers and switchable layers — OpenStreet, Google, HERE, Tencent, or custom.
• Supports Markers, Polygons, Circles, and Polylines overlays simultaneously on the same map.
• Includes interactive editing tools — place, move, and remove markers, polygons, and circles directly on the widget.

1. Open the dashboard and switch to edit mode.
2. Click Add widget at the top, or the Add new widget icon in the center of the screen.
3. Open the Maps widget bundle.
4. Select Map.
5. Configure the widget settings, then click Add.

Configure one or more tile layers for the map background:

• Label: Display name shown in the layer switcher on the widget.
• Provider: OpenStreet, Google, HERE, Tencent, or Custom (enter a tile server URL).
• Layer: Tile style — Mapnik, HOT, WorldStreetMap, WorldTopoMap, WorldImagery, Roadmap, etc. Available options depend on the provider.
• Reference layer: A transparent overlay with labeled map elements (streets, borders). Configure via the layer gear icon menu.

Click Add layer to configure additional switchable layers. Users switch between layers using the layer icon button directly on the widget.

Overlays are the visual elements rendered on the map. Each overlay type binds to its own data source and is configured independently.

[[lat1,lng1],[lat2,lng2],...,[latN,lngN]]

[[53.37545,-6.31259],[53.37554,-6.31256],[53.37537,-6.31128],[53.37547,-6.31124]]

{"latitude": value, "longitude": value, "radius": value}

{"latitude": 53.4791, "longitude": -6.5172, "radius": 137.74}

[[lat1,lng1],[lat2,lng2],...,[latN,lngN]]

Additional datasources provide telemetry or attributes from entities not directly displayed on the map. Use them in overlay functions for conditional logic — color-changing markers, enriched tooltips, or computed display values based on data from related devices.

• Source: Entity type — Function, Device, or Entity alias.
• Data keys: Telemetry or attribute keys to read from the entity.

Click Add datasource to configure more.

Configure the interactive controls available on the widget.

Position — placement of the controls panel: Top-left, Top-right, Bottom-left, or Bottom-right.

Zoom actions — enable zoom via:

• Scroll: Mouse wheel zoom.
• Double click: Zoom in on double-click.
• Control buttons: Show + / − zoom buttons on the map.

Scale — display a distance scale bar: Metric (km / m) or Imperial (mi / ft).

Add custom buttons overlaid on the map. Each button triggers a predefined action when clicked.

Each button has a Label, Icon, Color, and Action.

Available action types: Do nothing, Navigate to new dashboard state, Update current dashboard state, Navigate to other dashboard, Custom action, Custom action (HTML template), Mobile action, Open URL, Place map item.

The Place map item action lets users click a point on the map to create a new entity at that location — coordinates are saved automatically as entity attributes.

Click Add button to configure more buttons.

For action configuration details, see Widget actions.

• Fit map bounds to cover all markers: Auto-adjusts zoom and position on load to fit all visible map items. Enabled by default.
• Default map center position: Initial map center coordinates (latitude, longitude) used when auto-fit is disabled.
• Default map zoom level: Initial zoom level. Higher values zoom in closer (like 7 for country level, 15 for street level).
• Limit of entities to load: Maximum entities loaded simultaneously. Prevents performance issues with large datasets (default: 16384).

• Title: Widget header label. Disabled by default. Use ${entityName} or ${entityLabel} as pattern variables, or enter a static string.
• Card icon: Icon displayed next to the title in the header. Set size (px), alignment, and color.

• Background: Card background color.
• Show card buttons: Toggle Data export and Fullscreen buttons in the widget header.
• Card border radius: Corner rounding in px (default: 0px).
• Card padding: Inner spacing between content and card edge in px (default: 8px).

Add Widget header button actions — icon buttons in the widget header that trigger a configured action when clicked.

See Widget actions for available action types and configuration.

Goal: Display two temperature and humidity sensors as markers on a map. Each marker shows live telemetry in a tooltip and links to a dedicated sensor detail state.

Download the example

You can download the complete dashboard for this example and import it into your own instance.

Prerequisites

1. Download and import the base dashboard into your instance. It contains two states: a main state (where the Map widget will be added) and a sensor_details state already configured to display telemetry for the selected sensor.

2. Create two devices named Sensor A1 and Sensor D1 that send temperature and humidity telemetry to ThingsBoard.

3. Set the following server-side attributes on each device:

   Sensor A1:

   • active: true
   • latitude: 53.4711462520356
   • longitude: -6.507791078415879

   Sensor D1:

   • active: true
   • latitude: 53.4836805758458
   • longitude: -6.532912864923978

   Alternatively, download the CSV file and use bulk provisioning to import both devices with the required attributes.

Step 1: Add the widget

Open the dashboard in edit mode and add a Map widget.

Step 2: Configure the widget

Map type

Select Map and configure three layers:

Overlays

Go to Overlays ⇾ Markers and click Add marker. Configure the datasource and keys:

• Datasource: Entity alias — create a new alias named Sensors
  • Filter type: Device type
  • Device types: temperature-sensor
• Latitude key: latitude
• Longitude key: longitude
• Additional data keys: temperature, humidity, active

Map type: Map with three layers. Overlay: Markers, datasource entity alias "Sensors", latitude/longitude keys, additional data keys: temperature, humidity, active. Keys: latitude key, longitude key, additional data keys: temperature, humidity, active. Entity alias "Sensors": Filter type — Device type, Device types — temperature-sensor.

Configure marker appearance:

• Marker: Icon — Thermostat, size 48
• Color function:

if (data.active !== "true") {
  return 'rgb(255, 0, 0)';
} else {
  return 'rgb(39, 134, 34)';
}

• Label function:

var color;
if (data.active !== "true") {
  color = 'rgb(255, 0, 0)';
} else {
  color = 'rgb(39, 134, 34)';
}
return '<span style="border: solid ' + color + '; border-radius: 10px; color: ' + color + '; background-color: #fff; padding: 3px 5px; font-size: 14px; position: relative; bottom: 6px;">' +
  '${entityLabel}' +
'</span>';

• Tooltip function:

const unit = { from: '°C', METRIC: '°C', IMPERIAL: '°F', HYBRID: '°C' };
var usrUnit = ctx.unitService.getTargetUnitSymbol(unit);
var unitValue = ctx.unitService.convertUnitValue(data.temperature, unit).toFixed(1);
return `<b>${data.entityName}</b><br/><br/><b>Temperature:</b> ${unitValue} ${usrUnit}<br/><b>Humidity:</b> ${data.humidity} %<br/><br/><link-act name="navigate_to_details">Sensor details</link-act><br/>`;

• Tag action:
  • Name: navigate_to_details
  • Action: Navigate to new dashboard state
  • Target dashboard state: sensor_details

Appearance

Disable the Title display.

Card appearance

Disable the Fullscreen card button.

Click Add to insert the widget into the dashboard. Resize and reposition as needed, then save the dashboard.

Step 3: Interact with markers

Click any marker to view the sensor’s temperature and humidity in the tooltip. Click Sensor details to navigate to the detail state, which shows current and historical readings for the past hour.

Click any marker to view additional information. The tooltip displays temperature and humidity values. Click "Sensor details" to navigate to the sensor detail state. The sensor detail state shows current and historical temperature and humidity data for the past hour.

Result

The Map widget shows both sensors as thermostat icons on the map — green when active, red when inactive. Clicking a marker reveals live telemetry and a link to the sensor’s historical data view.

Markers not visible:

• Confirm the entity has latitude and longitude attributes or telemetry populated.
• Check that the coordinate key names in the widget configuration match the entity’s actual key names exactly.
• Verify the values are valid decimal coordinates, not strings or null.

Polygon or circle not displayed:

• Confirm the attribute key exists on the entity and the value format is correct.
• For polygons: [[lat1,lng1],[lat2,lng2],...].
• For circles: {"latitude":value,"longitude":value,"radius":value}.

Polyline not shown:

• Confirm the entity has the polyline attribute with the correct key name.
• Verify the attribute value follows the expected format: [[lat1,lng1],[lat2,lng2],...].

Map loads blank:

• For Google Maps, HERE, or Tencent — verify the API credentials are configured in ThingsBoard system settings.
• For OpenStreetMap, no credentials are required.

Markers cluster even at high zoom:

• Check whether Use map markers clustering is enabled on the marker overlay. Disable it if individual markers are needed at all zoom levels.