Image Map

The Image Map widget displays entities on a custom image background instead of a tile-based geographic map. Upload a floor plan, equipment layout, or any site diagram, then place markers, polygons, and circles on it — linked to live telemetry from your devices.

Use it for indoor positioning, smart building visualizations, parking lot monitoring, factory floor layouts, or any scenario where a geographic map is not the right background.

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

What sets Image Map apart:

• Uses any uploaded image as the map background — floor plans, diagrams, schematics.
• Entity positions are defined as relative coordinates (0 to 1), not latitude/longitude.
• Supports interactive editing — place, move, and remove markers, polygons, and circles directly on the widget.
• Supports Markers, Polygons, Circles, and Polylines overlays.

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 Image Map.
5. Configure the widget settings, then click Add.

Image Map always uses an image as its background. Configure the image source:

• Image source — Image: Upload a static image from your local machine or select one from the ThingsBoard Image Gallery. Supports PNG, JPEG, and other common formats.
• Image source — Entity key: Load the background image dynamically from an entity attribute or telemetry value.
  • Source entity alias: The entity alias that holds the image URL key.
  • Image URL key: The attribute or telemetry key whose value is the image URL.

Use Entity key when different entities display different floor plans, or when the background image should update at runtime.

Overlays are the visual elements placed on top of the image. Each overlay type binds to its own data source and is configured independently.

return {x: origXPos, y: origYPos};

var xPos = data.xPos;
var yPos = data.yPos;
var locationGroup = dsData.filter((item) => item.xPos === xPos && item.yPos === yPos);
if (locationGroup.length > 1) {
  const count = locationGroup.length;
  const index = locationGroup.indexOf(data);
  const radius = 0.035;
  const angle = (360 / count) * index - 45;
  const x = xPos + radius * Math.sin(angle * Math.PI / 180) / aspect;
  const y = yPos + radius * Math.cos(angle * Math.PI / 180);
  return {x: x, y: y};
} else {
  return {x: xPos, y: yPos};
}

[[x1,y1],[x2,y2],...,[xN,yN]]

[[0.313,0.445],[0.974,0.425],[0.963,0.941],[0.43,0.812],[0.362,0.804]]

[x, y, radius]

[0.344, 0.595, 0.23]

[[x1,y1],[x2,y2],...,[xN,yN]]

[[0.1,0.5],[0.3,0.5],[0.3,0.8],[0.7,0.8]]

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. Choose Metric (km / m) or Imperial (mi / ft). For floor plans and custom images, disable scale if real-world distances are not relevant.

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.

Click Add button to configure more buttons.

For action configuration details, see Widget actions.

• 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 an apartment floor plan on the Image Map, place a temperature sensor marker on it, and show the current temperature in real time with color-coded status.

Download the example widget

You can download a preconfigured Image Map widget for this example and reuse it in your own dashboards.

After importing, update the target entity to match your environment.

Prerequisites

1. Download the apartment plan image and upload it to the ThingsBoard Image Gallery.
2. Create a device named Smart Device that sends a temperature telemetry key to ThingsBoard.

Step 1: Add the widget

Open the dashboard in edit mode and add an Image Map widget.

Step 2: Configure the widget

Map type

• Image source: Image
• Image file: Select the apartment plan image from the gallery.

Overlays

Overlays ⇾ Markers and click Add marker. Configure:

• Source: Device — Smart Device
• X position key: xPos
• Y position key: yPos
• Additional data keys: temperature

Configure marker appearance:

• Marker: Icon — Thermostat, size 36
• Color settings: Range
  • Color range source key: temperature
  • Color range: Blue (below 20) → Green (20–25) → Red (above 25)
• Label pattern:

<div style='position: relative; white-space: nowrap; text-align: center; font-size: 14px; top: 2px;'><span style='margin-left: -500%;'></span><div style='border: 2px solid #00695c; border-radius: 10px; color: #000; background-color: #fff; padding-left: 12px; padding-right: 12px; padding-top: 4px; padding-bottom: 4px;'>${entityLabel}</div></div>

• Tooltip pattern:

<b>${entityName}</b><br/><br/><b>Temperature:</b> ${temperature} °C

Configure edit tools:

• Instruments: Add, Move, Remove
• Scope: Server

Map controls

Disable Scroll and Double click zoom.

Appearance

Set the title: Sensor Map

Card appearance

Set Card border radius: 12px.

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

Step 3: Place the marker on the map

1. In the left panel of the Image Map widget, click Place marker.
2. Click on any area of the floor plan image to place the marker at that position.
3. The marker for Smart Device appears at the selected location.

You can drag the marker to adjust its position, or click it and select Remove marker to delete it.

In the left panel of the Image Map widget, click the Place marker button. Click on an empty area of the floor plan to place the marker. The temperature sensor marker appears on the Image Map at the selected location.

Result

The Image Map widget displays the apartment floor plan with a thermostat marker positioned in the living room. The marker changes color based on the current temperature — blue when cool, green when normal, red when warm. Hovering over the marker opens a tooltip with the precise reading.

Goal: Draw a polygon on the apartment floor plan that represents the robot vacuum’s cleaning zone, linked to a device attribute.

Download the example widget

You can download a preconfigured Image Map widget for this example and reuse it in your own dashboards.

After importing, update the target entity to match your environment.

Prerequisites

1. Download the apartment plan image and upload it to the ThingsBoard Image Gallery.
2. Create a device named Robot Vacuum.

Step 1: Add the widget

Open the dashboard in edit mode and add an Image Map widget.

Step 2: Configure the widget

Map type

• Image source: Image
• Image file: Select the apartment plan image from the gallery.

Overlays

Overlays ⇾ Polygons and click Add polygon. Configure:

• Source: Device — Robot Vacuum
• Polygon key: perimeter

Configure polygon appearance:

• Fill: Color — #3388FF33
• Stroke: 0px
• Tooltip pattern: <b>Robot vacuum working area</b>
• Tooltip trigger: Show on hover

Configure edit tools:

• Instruments: Add, Remove
• Scope: Server

Map controls

Disable Scroll and Double click zoom.

Appearance

Set the title: Apartment plan #8

Card appearance

Set Card border radius: 12px.

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

Step 3: Draw the polygon on the map

1. In the left panel of the Image Map widget, click Draw rectangle or Draw polygon.
2. Click on the floor plan to place the first point of the polygon.
3. Continue clicking to add additional points along the boundary.
4. Click the first point again to close the shape and save it.

The polygon appears on the Image Map, representing the defined cleaning area. You can reshape it later using the Edit tool or reposition it with the Move tool.

In the left panel of the Image Map widget, select Draw rectangle or Draw polygon. Click on the floor plan to place the first point, then click to add additional points. Click the first point again to close the shape and save it. The polygon appears on the Image Map, representing the robot vacuum cleaning zone.

Result

The Image Map widget displays the apartment floor plan with a semi-transparent blue polygon outlining the robot vacuum’s operating area. Hovering over the polygon shows a tooltip.

Goal: Visualize the Wi-Fi router’s signal coverage area as a circle on the apartment floor plan.

Download the example widget

You can download a preconfigured Image Map widget for this example and reuse it in your own dashboards.

After importing, update the target entity to match your environment.

Prerequisites

1. Download the apartment plan image and upload it to the ThingsBoard Image Gallery.
2. Create a device named Wi-Fi Router.

Step 1: Add the widget

Open the dashboard in edit mode and add an Image Map widget.

Step 2: Configure the widget

Map type

• Image source: Image
• Image file: Select the apartment plan image from the gallery.

Overlays

Overlays ⇾ Circles and click Add circle. Configure:

• Source: Device — Wi-Fi Router
• Circle key: perimeter

Configure circle appearance:

• Fill: Color — #3388FF33
• Stroke: 2px — #048AD3
• Tooltip pattern: <b>${entityName}</b>
• Tooltip trigger: Show on hover

Configure edit tools:

• Instruments: Add, Remove
• Scope: Server

Map controls

Disable Scroll and Double click zoom.

Appearance

Set the title: Apartment plan #8

Card appearance

Set Card border radius: 12px.

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

Step 3: Draw the circle on the map

1. In the left panel of the Image Map widget, click Draw circle.
2. Click on the floor plan to place the center of the circle at the router’s location.
3. Move the mouse to set the desired radius, then click again to create and save the circle.

You can adjust the circle’s size or position later using the Edit circle tool.

In the left panel of the Image Map widget, select Draw circle. Click on the floor plan to place the center of the circle at the router location. Move the mouse to set the desired radius, then click to save the circle. The circle appears on the Image Map, representing the Wi-Fi coverage area in the apartment.

Result

The Image Map widget displays the apartment floor plan with a blue circular overlay showing the Wi-Fi router’s approximate signal range. Hovering over the circle shows a tooltip with the router name.

Marker not visible after saving:

• Confirm that the entity has the x and y position keys populated as attributes. If the keys are empty, the marker has no position and is not rendered.
• Check that the key names in the widget configuration match exactly the attribute key names on the entity.
• Use the Place marker tool on the widget’s left panel to position the marker interactively — this writes the xPos and yPos attributes to the entity automatically.

Polygon or circle not displayed:

• Verify the attribute key exists on the entity and that the value format is correct.
• For polygons: [[x1,y1],[x2,y2],...] with values between 0 and 1.
• For circles: [x, y, radius] with x and y between 0 and 1.
• Use the Draw polygon or Draw circle tool on the widget to create the shape interactively and have the attribute written automatically.

Background image not loading:

• If using Image source: Image, confirm the image was uploaded to the ThingsBoard Image Gallery.
• If using Image source: Entity key, confirm the entity has the attribute key populated with a valid image URL.

Edit tools not appearing on the widget:

• Enable the corresponding instruments (Add, Move, Remove, Edit) in the overlay’s Edit marker / Edit polygon / Edit circle section.