Skip to main content
Version: 5.0

Interactivity

This guide explains how to enhance a map's interactivity by making locations clickable. Interactivity can greatly improve the user experience and engagement with your maps.

Hover Interactivity​

Once the showVenue promise returns, the map is loaded and ready to be interacted with. Using the returned MapView, interactivity can be enabled for the map. Call addInteractivePolygonsForAllLocations to do so.

import { getVenue, showVenue, TGetVenueOptions, E_SDK_EVENT } from '@mappedin/mappedin-js';
import '@mappedin/mappedin-js/lib/mappedin.css';

// See Trial API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
const options: TGetVenueOptions = {
	venue: 'mappedin-demo-mall',
	clientId: '5eab30aa91b055001a68e996',
	clientSecret: 'RJyRXKcryCMy4erZqqCbuB1NbR66QTGNXVE0x3Pg6oCIlUR1',
};

async function init() {
	const venue = await getVenue(options);
	const mapView = await showVenue(document.getElementById('app')!, venue);

	mapView.addInteractivePolygonsForAllLocations(); // if user hovers over a polygon , it will indicate that it's clickable
}
init();

Hovering over a polygon that has a location attached to it will now change its color and the cursor to indicate that the polygon is clickable. However, nothing will happen when clicking on the polygons.

Handling Click Events​

In Mappedin SDK v5, POLYGON_CLICKED and NOTHING_CLICKED have been deprecated in favor of CLICK. To capture the click event, add a listener for E_SDK_EVENT.CLICK and change the color of the polygon in the callback function. Colors will be cleared when a user clicks outside of interactive polygons.

mapView.on(E_SDK_EVENT.CLICK, ({ polygons }) => {
	if (polygons.length > 0) {
		mapView.setPolygonColor(polygons[0], '#BF4320');
	} else {
		mapView.clearAllPolygonColors();
	}
});

CodeSandbox Example​

The CodeSandbox below demonstrates this functionality.

Interactive Floating Labels​

Interactivity can also be enabled for FloatingLabels by calling the labelAllLocations method and passing interactive: true. The E_SDK_EVENT.CLICK event will then be fired when a user clicks on a FloatingLabel.

The code sample below enables interactivity for all FloatingLabels and captures their click event. When a label is clicked, the corresponding polygon turns red. If the user clicks outside of a label, all polygons are reset to their original colors.

mapView.FloatingLabels.labelAllLocations({ interactive: true });

mapView.on(E_SDK_EVENT.CLICK, ({ floatingLabels }) => {
	if (floatingLabels && floatingLabels.length > 0) {
		mapView.setPolygonColor(floatingLabels[0].node.polygon, 'red'); //sets clicked Polygon color to 'red'
	} else {
		mapView.clearAllPolygonColors(); // clears all clicked Polygons
	}
});

For more information on FloatingLabels, refer to the Floating Labels Guide.

CodeSandbox Example​

The following Codesandbox demonstrates the sample code above within a full app.

Interactive Paths​

To enable interactivity for Journey and Paths, set the interactive: true in the TPathOptions

Start by generating directions from a start and end location.

const startLocation = venue.locations.find((location) => location.name === 'ThinkKitchen')!;
const endLocation = venue.locations.find((location) => location.name === 'American Eagle')!;
const directions = startLocation.directionsTo(endLocation);

For more information on directions and wayfinding, read the A-B Wayfinding guide.

Next, draw the Journey or Path for the directions and enable the interactive option.

// Journey
mapView.Journey.draw(directions, {
	pathOptions: {
		interactive: true,
	},
});

// Paths
mapView.Paths.add(directions.path, {
	interactive: true,
});

Handling Path Click Events​

The mouse cursor will adapt to a pointer when hovering an interactive Path. On mouse click the E_SDK_EVENT.CLICK listener will return the array of Paths at the selected point on the map.

To make changes to the Journey or Path selected, redraw it with the Path passed to the event and new options.

// Journey
mapView.on(E_SDK_EVENT.CLICK, ({ paths }) => {
	paths?.forEach((path) => {
		mapView.Journey.clear();
		const directions = path.nodes[0].directionsTo(path.nodes[path.nodes.length - 1]);
		mapView.Journey.draw(directions, {
			pathOptions: { color: '#BF4320', animateDrawing: false },
		});
	});
});

// Paths
mapView.on(E_SDK_EVENT.CLICK, ({ paths }) => {
	paths?.forEach((path) => {
		mapView.Paths.remove(path);
		mapView.Paths.add(path.nodes, {
			color: '#BF4320',
			animateDrawing: false,
		});
	});
});

CodeSandbox Example​

The following sample shows two interactive Paths. When clicked, they will be drawn in a new color. Clicking anywhere else on the map will reset them both.

Interactive Markers​

Markers can be set to interactive to allow an app to detect when the user clicks on them. This is done by setting interactive to true in the TCreateMarkerOptions object when adding the marker. Refer to the Marker Guide for more information on using Markers.

Adding an interactive marker:

const markerTemplate = `
  <div class="marker">
    <p>It's a Marker!</p>
  </div>`;

mapView.Markers.add(nodeOrCoordinate, markerTemplate
    { interactive: true });

CodeSandbox Example​

The CodeSandbox below demonstrates interactive Markers. Click on a store to create a Marker and then click on the Marker to remove it.

Interactive Tooltips​

Enabling interactivity for a tooltip allows an app to perform an action when the user clicks on it. This is accomplished by setting interactive to true in the TCreateTooltipOptions object when adding the marker. Refer to the Tooltips Guide for more information on using tooltips.

Creating an interactive tooltip:

mapView.createTooltip(nodeOrCoordinate, `<div tabindex="0" style="padding: 10px;">A Tooltip!</div>`, {
	interactive: true,
});

CodeSandbox Example​

The CodeSandbox below demonstrates interactive Tooltips. Click on a store to create a Tooltip and then click on the Tooltip to remove it.

Additional Reading​

For more information on advanced use cases and integration possibilities, explore these resources.