Labels
Mappedin SDK for React Native version 6 is currently in an alpha 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 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.
Note that the MapViewControl class implements the Mappedin.Labels interface and exposes it as MapViewControl.Labels. Use MapViewControl.Labels to utilize Labels' methods. An instance of MapViewControl is available from the useMap hook.
Displaying All Labels
To display all labels that have been added to the source map, use the Mappedin.Labels.all(). The following code sample demonstrates use of the all()
method:
- Declarative
- Imperative
// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);
// Add labels for all spaces
return (
<>
{spaces.map(space => (
<Label
key={space.externalId}
target={space}
text={space.name}
/>
))}
</>
);
// Add all the labels to the map.
mapView.Labels.all();
The opposite of the all()
method is the Mappedin.Labels.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 Mappedin.Labels.add(). A label can be added to any Mappedin.IAnchorable target. The following code sample adds a label to each space that has a name:
- Declarative
- Imperative
// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);
// Label all spaces with its space name and make them interactive.
return (
<>
{spaces.map(space => (
<Label
key={space.externalId}
target={space}
text={space.name} // label text
options={{ interactive: true }} // makes the label interactive
/>
))}
</>
);
// 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, { interactive: true });
}
});
Labels can be removed by using the Mappedin. 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 Mappedin.TLabelAppearance.iconFit parameter with contain
being the default.
Fill | Contain | Cover (default) |
---|---|---|
![]() | ![]() | ![]() |
The Mappedin.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 Mappedin.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 Mappedin.TLabelAppearance describes these customisable attributes.
interface TLabelAppearance {
margin?: number;
marker?: {
backgroundColor?: { active?: string; inactive?: string };
foregroundColor?: { active?: string; inactive?: string };
icon?: string;
iconFit?: "fill" | "contain" | "cover";
iconOverflow?: "visible" | "hidden";
iconPadding?: number;
iconScale?: number | Interpolation<"zoom-level", number[]>;
iconSize?: number;
iconVisibleAtZoomLevel?: number;
};
text?: {
backgroundColor?: string;
foregroundColor?: string;
lineHeight?: number;
maxWidth?: number;
numLines?: number;
size?: number;
};
}
Mappedin.TLabelAppearance
Margin:
margin
in pixels around the label and marker. This will affect label density.
Marker styles:
backgroundColor
&foregroundColor
The marker takes bothactive
andinactive
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:
foregroundColor
andbackgroundColor
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.
<Label
key="sirens-label"
target={sirenSpace}
text={`🎵 Sirens`}
options={{
interactive: true,
rank: "high",
appearance: {
text: {
foregroundColor: "#E91E63",
},
marker: {
foregroundColor: {
active: "#4CAF50",
inactive: "#999",
},
icon: "https://your-domain.com/icons/your-icon.svg",
},
},
}}
onLoad={(label) => {
console.log("Sirens label loaded:", label);
}}
/>
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 Mappedin.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.
- Declarative
- Imperative
const [labels, setLabels] = useState<
{
coordinate: Mappedin.Coordinate;
text: string;
rank: Mappedin.TCollisionRankingTier;
}[]
>([]);
const RANKS: Mappedin.TCollisionRankingTier[] = ['low', 'medium', 'high', 'always-visible'];
const [currentRank, setCurrentRank] = useState(0);
// Handle map clicks to add a label with a cycling rank
useEvent('click', event => {
const newRank = (currentRank + 1) % RANKS.length; // Cycle through ranks
setCurrentRank(newRank);
const newLabel = {
coordinate: event.coordinate,
text: `Label Rank ${RANKS[newRank]}`,
rank: RANKS[newRank],
};
setLabels(prevLabels => [...prevLabels, newLabel]);
});
return (
<>
{labels.map((label, index) => (
<Label
key={index} // Use index as a fallback key for simplicity
target={label.coordinate} // Add the label to the clicked coordinate
text={label.text}
options={{
rank: label.rank, // Set the rank for the label
}}
/>
))}
</>
);
const RANKS: TCollisionRankingTier[] = ['low', '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 4 possible ranks. If rank exceeds 3, reset it to 0.
if (currentRank > 3) {
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],
});
});
Enabling and Disabling Labels
Labels can be dynamically enabled or disabled using MapViewControl.updateState() or the Mappedin.TAddLabelOptions.enabled. 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.
Use MapViewControl.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:
- Declarative
- Imperative
const [isEnabled, setIsEnabled] = useState(false);
return (
<Label
target={space}
text="Dynamic Label"
options={{
enabled: isEnabled // label will be hidden when false
}}
/>
);
let coordinate;
let label;
mapView.on("click", async (event) => {
// first click - add label
if (!label) {
console.log("Adding label at:", event.coordinate);
coordinate = event.coordinate;
label = await mapView.Labels.add(
coordinate,
"Click to Toggle!",
{
interactive: true,
enabled: true
}
);
} else {
// get current state of label
const labelState = mapView.getState(label);
console.log("Current Label State:", labelState);
// toggle enabled state
const newState = !labelState.enabled;
mapView.updateState(label, { enabled: newState });
console.log(`Label is now ${newState ? "enabled" : "disabled"}`);
}
});
A common use case is showing different sets of labels based on zoom level:
- Declarative
- Imperative
const [secondaryLabels, setSecondaryLabels] = useState(
spaces.slice(5).map(space => ({
target: space,
text: space.name,
enabled: false
}))
);
useEvent('camera-change', (transform) => {
setSecondaryLabels(labels =>
labels.map(label => ({
...label,
enabled: transform.zoomLevel >= 20
}))
);
});
return (
<>
{/* primary labels - always visible */}
{spaces.slice(0, 5).map(space => (
<Label
key={space.id}
target={space}
text={space.name}
options={{ enabled: true }}
/>
))}
{/* secondary labels - conditionally visible */}
{secondaryLabels.map(label => (
<Label
key={label.target.id}
target={label.target}
text={label.text}
options={{ enabled: label.enabled }}
/>
))}
</>
);
// init secondary labels - hidden until zoomed in
secondaryLabels = mapData
.getByType("space")
.filter((space) => space.name !== "")
.slice(40, 60)
.map((space) => ({
target: space,
text: "Secondary: " + space.name,
options: { interactive: true, enabled: true },
labelInstance: undefined,
}));
// add secondary labels, then immediately disable them
secondaryLabels.forEach(async (label) => {
label.labelInstance = await mapView.Labels.add(
label.target,
label.text,
label.options
);
// store ref and disable initially
mapView.updateState(label.labelInstance, { enabled: false });
});
// handle camera change to toggle secondary labels
mapView.on("camera-change", (transform) => {
if (transform.zoomLevel < 19) {
secondaryLabels.forEach((label) => {
if (label.labelInstance) {
mapView.updateState(label.labelInstance, { enabled: false });
}
});
} else {
secondaryLabels.forEach((label) => {
if (label.labelInstance) {
mapView.updateState(label.labelInstance, { enabled: true });
}
});
}
});