Floating Labels

Map geometry alone is not enough to have a sense of a location. Let's add labels to name the stores and other points-of-interest in the Mappedin Demo Mall. We can add the Floating Labels with default styles easily with FloatingLabels.labelAllLocations().

However, this sample CodeSandbox does a bit more than just render the labels in the beginning. Try clicking on a polygon to see a styled label and outside of interactive polygons to reset the labels.

Styling Options

The following type declaration of appearance object describes the customizable attributes.

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

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.
• size was deprecated and is no longer used.
• icon is the SVG of icon to place inside Floating Label.
• iconSize is the size of bounding box of 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 label created by clicking on a polygon is styled to have a larger marker and larger, more colorful text.

mapView.FloatingLabels.add(polygons[0], location.name, {
	appearance: {
		marker: {
			size: 20,
		},
		text: {
			size: 32,
			foregroundColor: '#ffb702',
			backgroundColor: '#0a0a0a',
		},
	},
});

Labels can be removed individually using FloatingLabels.remove(polygonOrNode) or all at once with FloatingLabels.removeAll().

Adding Icons

Icons can be added to Floating Labels to highlight certain categories or to make locations more eye catching. These icons automatically adjust, becoming visible as the user zooms the map to view more detail. The supplied icon must be an SVG provided to the TFloatingLabelAppearance options in FloatingLabels.add().

For this demonstration, we'll use only a single icon defined below. For best results, a square icon with low detail is preferable. We've also defined some colors which we'll use to differentiate between location categories.

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 = ['dodgerblue', 'pink', 'green', 'orange', 'tomato', 'gray'];

We can use the list in the MappedinVenue class to iterate through locations and add their icons. At the same time, we'll apply color to the Floating Label's marker.

venue.categories.forEach((category, index) => {
	category.locations.forEach((location) => {
		if (location.polygons.length <= 0) {
			return;
		}
		const color = colors[index % colors.length];
		mapView.FloatingLabels.add(location.polygons[0], location.name, {
			appearance: {
				marker: {
					icon: icon,
					foregroundColor: {
						active: color,
						inactive: color,
					},
				},
			},
		});
	});
});

If you only wish to highlight a few locations using icons and apply a default appearance to the rest, this can be done by applying FloatingLabels.labelAllLocations() before overriding with FloatingLabels.add() as above.

Preset Themes

Mappedin JS comes with two preset Floating Label themes. labelThemes.darkOnLight is rendered by default. However, darker page themes might sometimes be preferable and the darker labels might look better. Use the dark mode themed labels by importing them and setting the appearance when labeling locations.

import { labelThemes } from '@mappedin/mappedin-js';

mapView.FloatingLabels.labelAllLocations({
	appearance: labelThemes.lightOnDark,
});

The appearance settings can be overridden but this theme provides a solid starting point for a darker visual style.