Version: 6.0

Labels

Using Mappedin SDK for Android with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

Labels display text and images anchored to specific points on a map. They rotate, show, or hide based on priority and zoom level, providing information about location names, points of interest, and more. Effective labels help apps convey additional information, such as room names, points of interest, main entrances, or other useful contextual details.

tip

A complete example demonstrating Labels can be found in the Mappedin Android Github repo: LabelsDemoActivity.kt

Mappedin v6 Labels

tip

Note that the MapView class instantiates the Labels class and exposes it as MapView.labels. Use MapView.labels to utilize Labels' methods.

Adding & Removing Individual Labels

Labels can be added individually to a map by calling Labels.add(). A label can be added to any Anchorable target. Refer to the Labels.add() documentation for the complete list of targets. The following code sample adds an interactive (clickable) label to each space that has a name:

mapView.mapData.getByType<Space>(MapDataType.SPACE) { result ->
  result.onSuccess { spaces ->
    for (space in spaces) {
      if (space.name.isNotEmpty()) {
        val color = colors.random()
        val appearance =
          LabelAppearance(
            color = color,
            icon = space.images.firstOrNull()?.url ?: svgIcon,
          )
        mapView.labels.add(
          target = space,
          text = space.name,
          options = AddLabelOptions(labelAppearance = appearance, interactive = true),
        )
      }
    }
  }
}

Labels can be removed by using the Labels.remove(label) method, passing in the label to be removed as shown below:

mapView.labels.remove(label)

Interactive Labels

Labels added to the map can be set to interactive to allow users to click on them. For more information, refer to the Interactive Labels section of the Interactivity Guide.

Label Icons

Icons can be added to labels in SVG, PNG, JPEG and WebP formats. Icons are clipped in a circle to prevent overflow. Three clipping methods of contain, fill and cover can be set in the LabelAppearance.iconFit parameter with contain being the default.

Fill	Contain	Cover (default)

The LabelAppearance.iconPadding property sets the amount of space between the icon and the border. The icon may shrink based on this value.

`padding: 0`	`padding: 10`

Label icons can be configured to be shown or hidden based on the current zoom level using LabelAppearance.iconVisibleAtZoomLevel. A value below 0 will result in the icon always being hidden. Setting this value to 0 ensures icons show up at maxZoom (fully zoomed in) and 1 configures them to always be displayed.

Label Appearance

Labels can have their appearance styled to match the visual theme of an app or to make groups of labels easily distinguishable from one another. The following declaration of LabelAppearance describes these customisable attributes.

Option	Type	Description	Default
`margin`	`number`	Margin around the label text and pin in pixels. This will affect label density. Minimum is 6px.	6
`maxLines`	`number`	Number of lines to display when text spans multiple lines.	2
`textSize`	`number`	Text size in pixels	11.5
`maxWidth`	`number`	Maximum width of text in pixels.	150
`lineHeight`	`number`	Line height sets the height of a line box. It's commonly used to set the distance between lines of text.	1.2
`color`	ColorString	A ColorString for the label text and pin.	`#333`
`outlineColor`	ColorString	A ColorString for the outline around the label text and pin.	`white`
`textColor`	ColorString	A ColorString representing just the text color. Defaults to the same as `color`.	-
`textOutlineColor`	ColorString	A ColorString representing just the text outline. Defaults to the same as `outlineColor`.	-
`pinColor`	ColorString	A ColorString representing just the pin color. Defaults to the same as `color`.	-
`pinOutlineColor`	ColorString	A ColorString representing just the pin outline. Defaults to the same as `outlineColor`.	-
`pinColorInactive`	ColorString	A ColorString representing just the pin color when the label is inactive. Defaults to the same as `pinColor`.	-
`pinOutlineColorInactive`	ColorString	A ColorString representing just the pin outline when the label is inactive. Defaults to the same as `pinOutlineColor`.	-
`icon`	`string`	An icon to be placed inside the label pin. Can be an SVG string or a path to a PNG or JPEG.	-
`iconSize`	`number`	Size of the icon in pixels. Requires `icon` to be set.	20
`iconScale`	`number` \| Interpolation	Scale the icon uniformly. Specify a number or an Interpolation object.	1
`iconPadding`	`number`	Padding between the icon and the marker's border in pixels.	2
`iconFit`	`'fill'` \| `'contain'` \| `'cover'`	How the icon should fit inside the marker. Options: `fill` (stretch to fill), `cover` (maintain aspect ratio and fill), `contain` (maintain aspect ratio and fit inside).	`cover`
`iconOverflow`	`'visible'` \| `'hidden'`	Whether the icon should overflow the circle of the marker. Options: `visible`, `hidden`.	`hidden`
`iconVisibleAtZoomLevel`	`number`	Defines the zoom level at which the icon becomes visible. Infinity ensures never visible, -Infinity ensures always visible.	-Infinity

The code sample below demonstrates how to use some label styling options. Labels are added to each space with a name using the space's image if one is set, or a default SVG icon if one is not. It also sets the label text color to a random color from a list of colors.

val svgIcon =
  """
  <svg width="92" height="92" viewBox="-17 0 92 92" fill="none" xmlns="http://www.w3.org/2000/svg">
    <g clip-path="url(#clip0)">
    <path d="M53.99 28.0973H44.3274C41.8873 28.0973 40.7161 29.1789 40.7161 31.5387V61.1837L21.0491 30.7029C19.6827 28.5889 18.8042 28.1956 16.0714 28.0973H6.5551C4.01742 28.0973 2.84619 29.1789 2.84619 31.5387V87.8299C2.84619 90.1897 4.01742 91.2712 6.5551 91.2712H16.2178C18.7554 91.2712 19.9267 90.1897 19.9267 87.8299V58.3323L39.6912 88.6656C41.1553 90.878 41.9361 91.2712 44.669 91.2712H54.0388C56.5765 91.2712 57.7477 90.1897 57.7477 87.8299V31.5387C57.6501 29.1789 56.4789 28.0973 53.99 28.0973Z" fill="white"/>
    <path d="M11.3863 21.7061C17.2618 21.7061 22.025 16.9078 22.025 10.9887C22.025 5.06961 17.2618 0.27124 11.3863 0.27124C5.51067 0.27124 0.747559 5.06961 0.747559 10.9887C0.747559 16.9078 5.51067 21.7061 11.3863 21.7061Z" fill="white"/>
    </g>
    <defs>
    <clipPath id="clip0">
    <rect width="57" height="91" fill="white" transform="translate(0.747559 0.27124)"/>
    </clipPath>
    </defs>
    </svg>
  """.trimIndent()

val colors = listOf("#FF610A", "#4248ff", "#891244", "#219ED4")

mapView.mapData.getByType<Space>(MapDataType.SPACE) { result ->
  result.onSuccess { spaces ->
    for (space in spaces) {
      if (space.name.isNotEmpty()) {
        val color = colors.random()
        val appearance =
          LabelAppearance(
            color = color,
            icon = space.images.firstOrNull()?.url ?: svgIcon,
          )
        mapView.labels.add(
          target = space,
          text = space.name,
          options = AddLabelOptions(labelAppearance = appearance, interactive = true),
        )
      }
    }
  }
}

Label Ranking

Ranking can be added to labels to control which label will be shown when more than one label occupies the same space. The label with the highest rank will be shown. If labels do not overlap, ranking will have no effect. Rank values are low, medium, high, and always-visible and are defined in CollisionRankingTier.

The code below add a label with a high ranking where a user clicks on the map.

mapView.on(Events.CLICK) { event ->
	val clickPayload = event as? ClickPayload ?: return@on
	mapView.labels.add(
		target = clickPayload.coordinate,
		text = "I'm a high ranking label!",
		options = AddLabelOptions(rank = CollisionRankingTier.HIGH),
	)
}

Enabling and Disabling Labels

Labels can be dynamically enabled or disabled using mapView.updateState(). When a label is disabled, it will be hidden from view but remain in the map's memory. This is useful for managing label visibility based on conditions like zoom level or user interaction, without the overhead of repeatedly adding and removing labels.

For Mappedin JS, use mapView.getState() to check a label's current state, which returns the label's current properties including its enabled status.

Here's an example on how to enable/disable labels on click:

private var label: Label? = null

...

mapView.on(Events.CLICK) { event ->
  val clickPayload = event as? ClickPayload ?: return@on
  if (label == null) {
    // Add the label if it doesn't exist.
    mapView.labels.add(
      target = clickPayload.coordinate,
      text = "Click to Toggle",
      onResult = {
        it.onSuccess {
          label = it
        }
      },
    )
  } else {
  // Toggle the label.
  label?.let { currentLabel ->
    mapView.getState(
      currentLabel,
      onResult = { result ->
        result.onSuccess { state ->
          Log.d("SOHM", state.toString())
          state?.let {
            mapView.updateState(
              currentLabel,
              LabelUpdateState(enabled = !it.enabled),
            )
          }
        }
      },
    )
  }
  }
}

tip

A complete example demonstrating Labels can be found in the Mappedin Android Github repo: LabelsDemoActivity.kt

Adding & Removing Individual Labels​

Interactive Labels​

Label Icons​

Label Appearance​

Label Ranking​

Enabling and Disabling Labels​