Labels

Mappedin SDK version 6 is currently in a beta state while Mappedin perfects new features and APIs. Open the v6 release notes to view the latest changes.

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

Labels contain text and an image that are anchored to a specific point on the map. They automatically rotate and show and hide based on priority and zoom level. Use them to inform users about location names, points of interest and more!

Effective use of labels allows an app to convey additional information to the user. For example labels can be used to show room names, important points of interest, main entrances or any other piece of contextual information that is useful to the user.

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

Video Walkthrough

Displaying All Labels

To display all labels that have been added to the source map, use the all() method of the Labels interface. The following code sample demonstrates use of the all() method:

// Add all the labels to the map.
mapView.Labels.all();

The opposite of the all() method is the removeAll() method, which removes all labels from the map.

// Remove all the labels from the map.
mapView.Labels.removeAll();

Adding & Removing Individual Labels

Labels can be added individually to a map by calling Label.add(). A label can be added to a Space, Door or Coordinate. The following code sample adds a label to each space that has a name:

// Label all spaces with its space name and make them interactive.
mapData.getByType('space').forEach((space) => {
	if (space.name) {
		mapView.Labels.add(space, space.name);
	}
});

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

// Remove a label.
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 TLabelAppearance.iconFit parameter with contain being the default.

Fill (default)	Contain	Cover

The TLabelAppearance.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 TLabelAppearance.iconVisibilityThreshold. 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 type declaration of TLabelAppearance describes these customisable attributes.

TLabelAppearance: {
    margin?: number;
    marker?: {
        backgroundColor?: {
            active?: string;
            inactive?: string;
        };
        foregroundColor?: {
            active?: string;
            inactive?: string;
        };
        icon?: string;
        iconSize?: number;
        iconVisibilityThreshold?: number;
        size?: number;
    };
    text?: {
        backgroundColor?: string;
        foregroundColor?: string;
        lineHeight?: number;
        maxWidth?: number;
        numLines?: number;
        size?: number;
    };
}

This CodeSandbox implements the example code above.

TLabelAppearance

Margin:

• margin in pixels around the label and marker. This will affect label density.

Marker styles:

• backgroundColor & foregroundColor The marker takes both active and inactive variants of its foreground and background colors.
• icon is the SVG of icon to place inside a label.
• iconSize is the size of the bounding box of the SVG icon.
• iconVisibilityThreshold defines when the icon becomes visible relative to the current zoom level. Values should be between 0 and 1. 0 appears at maximum zoom and 1 causes the marker to always be shown.

Text styles:

• foreground and background colors that can be set using CSS colors, as Hex strings or the CSS name of a color such as crimson.
• lineHeight sets the height of a text line box. The default is 1.2.
• maxWidth defines the maximum width of text in pixels.
• numLines sets the maximum number of lines to display if the text spans multiple lines.
• size is the text size in pixels.

The code sample below demonstrates how to use some label styling options. It specifies an SVG icon to use and sets the icon and text color. Labels are added to each space with a name.

// SVG image for the label's icon.
const icon = `<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>`;

const colors = ['blue', 'pink', 'green', 'orange', 'tomato', 'gray'];

// Label all spaces with its space name and add styling using a custom appearance and SVG icon.
mapData.spaces.forEach((space, index) => {
	if (space.name) {
		const color = colors[index % colors.length];

		mapView.Labels.add(space, space.name, {
			appearance: {
				marker: {
					foregroundColor: {
						active: color,
						inactive: color,
					},
					icon: icon,
				},
				text: {
					foregroundColor: color,
				},
			},
		});
	}
});

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 can range from 0 to 4 as defined in TCollisionRankingTier.

The code below adds labels where a user clicks on the map. The label rank is cycled with each click. If the user clicks and adds multiple labels in the same location, the label with the highest rank is shown and lower ranking labels are hidden.

const RANKS: TCollisionRankingTier[] = ['medium', 'high', 'always-visible'];
let currentRank = 0;

// Act on the click event and add a label with a cycling rank. Observe how higher ranking labels are shown when they collide with lower ranking labels.
mapView.on('click', async (event) => {
	currentRank++;
	// There are 3 possible ranks. If rank exceeds 2, reset it to 0.
	if (currentRank > 2) {
		currentRank = 0;
	}

	// Add a label with the current rank at the clicked coordinate.
	mapView.Labels.add(event.coordinate, 'Label Rank ' + RANKS[currentRank], {
		rank: RANKS[currentRank],
	});
});

The CodeSandbox below adds labels with a cycling rank, matching the code example above. Click to add a new label.