Wayfinding
Using Mappedin SDK for React Native with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.
Wayfinding is the process of navigating through environments using spatial cues and instructions to efficiently reach a destination. Mappedin SDK for React Native provides the tools needed to guide users from one location to another. It allows drawing a path between points on the map as well as creation of textual turn-by-turn directions for navigation.

Getting Directions
Directions form the core of wayfinding. Mappedin has path finding capabilities that allow it to generate directions from one target to another. These directions are used for drawing paths and providing the user with textual turn-by-turn directions.
A complete example demonstrating directions can be found in the Mappedin React Native GitHub repo: directions.tsx
Generate directions by calling MapViewControl.getDirections() and pass in targets for the origin and destination. These targets are wrapped in a Mappedin.TNavigationTarget, which can contain various types of targets.
MapViewControl.getDirections()can accept a single Mappedin.TNavigationTarget or an array of them for the origin and destination. If an array is used, Mappedin SDK for React Native will choose the targets that are closest to each other. An example of where this could be used is when a user asks for directions to a washroom. There may be many Spaces named Washroom. The app can pass all washroom spaces to getDirections and receive directions to the nearest one. An array of destinations is also used when creating multisegment directions, which are directions that include multiple legs.
Directions for some maps may appear jagged. This is the SDK finding the shortest path through the map's geometry. MapViewControl.getDirections() accepts Mappedin.TGetDirectionsOptions, which includes a smoothing option that simplifies the computed route by removing redundant waypoints. Route simplification is enabled by default for maps created using Mappedin Maker and disabled for maps created using Mappedin CMS.
This smoothing option is route simplification. It is unrelated to the visual smoothing option on Mappedin.TAddPathOptions, which rounds the corners of a drawn path and is covered in the Path Styles section.
Route Simplification
smoothing accepts true or false, or an object. The object fields are enabled, radius (meters, default 0.75), method, and includeDoorBufferNodes.
| Method | Behaviour |
|---|---|
'greedy-los' | Default. Greedy forward scan with line-of-sight validation. Fastest. |
'rdp' | Ramer-Douglas-Peucker preprocessing followed by line-of-sight validation. Medium speed, not globally optimal. |
'dp-optimal' | Dynamic programming that produces the shortest, straightest route. Slowest on long paths. |
includeDoorBufferNodes preserves door-adjacent nodes so a simplified route still passes cleanly through doorways. It defaults to true for 'rdp' and false for 'dp-optimal', and is ignored by 'greedy-los'.
Simplification never removes a node flagged to prevent smoothing, so doors and floor transitions are always kept. On Mappedin Maker maps, outdoor nodes carry that flag, so outdoor segments of a route are not simplified.
const directions = await mapView.getDirections(firstSpace, secondSpace, {
smoothing: {
enabled: true,
method: 'dp-optimal',
includeDoorBufferNodes: true,
radius: 0.4,
},
});
Enterprise maps can also exclude specific connections from routing with excludedConnections, an array of Mappedin.Connection. An excluded connection is never used, even when it is the only route, in which case getDirections returns undefined.
Drawing Navigation
When a user needs to get from point A to point B, drawing a path on the map helps them to navigate to their destination. It can help them to visualize the route they'll need to take, like a good treasure map.
Mappedin.Navigation is a helper class to display wayfinding easily on the map. Functionality of Mappedin.Navigation could be replicated by drawing the paths using Path and adding well designed markers at connection points.
Note that the MapViewControl class includes the Navigation class and exposes it as MapViewControl.Navigation. Use MapViewControl.Navigation to utilize Navigation's methods.
Navigation.draw() allows for easily drawing multiple components that make up a wayfinding illustration. It shows a human figure to mark the start point, a path with animated directional arrows, pulses in the direction of travel and a pin to mark the destination. Each of these components can be customized to match an app's style.
The following sample uses the default navigation settings to navigate from the Cafeteria to the Gymnasium.
// Get the spaces for the first and second spaces to navigate to and from.
const firstSpace = mapData.getByType('space').find(s => s.name === 'Cafeteria');
const secondSpace = mapData.getByType('space').find(s => s.name === 'Gymnasium');
// Ensure that the spaces exist.
if (firstSpace && secondSpace) {
const directions = await mapData.getDirections(firstSpace, secondSpace);
if (directions) {
// Add a path from the first space to the second space.
mapView.Navigation.draw(directions);
}
}
The navigation visualization can be customized by passing in a Mappedin.TNavigationOptions object to Navigation.draw(). The following example demonstrates how to customize the navigation visualization, using the pathOptions, markerOptions and createMarkers properties.
let navigationOptions: TNavigationOptions = {
pathOptions: {
displayArrowsOnPath: true,
animateArrowsOnPath: true,
accentColor: '#ffffff',
},
markerOptions: {
departureColor: '#228b22',
destinationColor: '#ff6347',
},
createMarkers: {
departure: (instruction: TDirectionInstruction) => {
const marker = mapView.Markers.add(instruction.coordinate, '<div>Departure</div>');
return marker;
},
destination: (instruction: TDirectionInstruction) => {
const marker = mapView.Markers.add(instruction.coordinate, '<div>Destination</div>');
return marker;
},
connection: (instruction: TDirectionInstruction) => {
const marker = mapView.Markers.add(instruction.coordinate, '<div>Connection</div>');
return marker;
},
},
};
mapView.Navigation.draw(directions, navigationOptions);
Highlighting a Portion of a Path
The path drawn by Navigation or Paths can have a portion highlighted to draw attention to it. This could be used to show the progress of a user's journey. To highlight a portion of the path, use the Navigation.highlightPathSection() or Paths.highlightSection() methods.
The following code demonstrates how to highlight a portion of a path, starting from the origin of directions and ending at a given coordinate. Note that the floor must be provided when using a coordinate to highlight a path section.
const coordinate = await mapView.createCoordinate(
Number(position.latitude),
Number(position.longitude),
position.floorOrFloorId
? mapData.getById("floor", position.floorOrFloorId)
: undefined
);
if (directions?.coordinates[0]) {
// Highlight the traveled path.
mapView.Navigation.highlightPathSection(
directions?.coordinates[0],
coordinate,
{
animationDuration: 0,
color: "#9d9d9d",
widthMultiplier: 1.1,
}
);
}
Illustrating Navigation Progress
When a user's position is available and a Blue Dot is shown, the drawn path can be kept in sync with where the user actually is. Navigation.trackCoordinate() takes the user's current Mappedin.Coordinate and updates the active path to reflect their progress. It is typically called on every position update, such as inside the Blue Dot's position-update event handler.
Navigation.trackCoordinate() supports two modes, configured through Mappedin.TTrackCoordinateOptions. Only one mode can be active at a time, and switching modes clears the previous mode's visual state. Use Navigation.stopTracking() to remove all tracking state.
Tethered Mode
Tethered mode anchors the path to the user's position so the directional path always begins at or near them. As the user moves, the portion of the path behind them is removed. The tetherThresholdDistance sets how far (in meters) the user can stray from the path before they are considered off-route. When the user is outside that threshold, coordinateOutsideThresholdMode controls the behaviour and outsideThresholdPathStyle (a Mappedin.TOutsideThresholdPathStyle) controls how the dashed connector back to the path is drawn.
// Snap the user's position onto the closest point on the active path.
useBlueDotEvent('position-update', useCallback((event) => {
mapView.Navigation.trackCoordinate(event.coordinate, {
mode: 'tethered',
tetherThresholdDistance: 10,
coordinateOutsideThresholdMode: 'tether-and-dash',
outsideThresholdPathStyle: 'dashed-boxes',
});
}, []));
Travelled Mode
Travelled mode keeps the full start-to-end path visible and recolours the portion the user has already walked past to show their progress. The color option sets the colour used for the travelled portion. Navigation.travelledFraction reports how far along the path the user has travelled as a value from 0 to 1.
// Recolour the portion of the path the user has walked past.
useBlueDotEvent('position-update', useCallback((event) => {
mapView.Navigation.trackCoordinate(event.coordinate, {
mode: 'travelled',
color: '#999',
});
}, []));
Navigating From a Click Event
A navigation start or end point may originate from a user clicking on the map. It is possible to create a start and or end point using the click event and accessing its Mappedin.TEvents payload. The code shown below uses the click position as a starting point to create directions. The width option is described in the Path Styles section later in this guide.
useMapViewEvent('click', async (payload: Mappedin.TClickPayload) => {
const clickedLocation = payload.coordinate;
const destination = mapData.getByType('space').find(s => s.name === 'Gymnasium');
// If the destination is found, navigate to it.
if (destination) {
//Ensure that directions could be generated (user clicked on a navigable space).
const directions = await mapData.getDirections(clickedLocation, destination);
if (directions) {
// Navigate from the clicked location to the gymnasium.
mapView.Navigation.draw(directions, {
pathOptions: {
width: 1,
},
});
}
}
});
Multi-Floor Wayfinding
Using Navigation, no additional work is needed to provide wayfinding between floors. Whenever a user needs to switch a floor, an interactive tooltip with an icon indicating the type of Mappedin.Connection (such as an elevator or stairs) will be drawn. By clicking or tapping the tooltip, the map view switches to the destination floor.
The vertical connection segment of a route can be styled independently of the floor segments. Mappedin.TNavigationOptions pathOptions accepts a nested connection object whose fields are the same path options documented in the Path Styles section. Each field set on connection fully replaces the matching base option for the connection segment only, including dash. For a multi-destination route, inactivePathOptions.connection styles the inactive route's connection the same way. A connection segment has its own end cap default: it ends square (endcapExtension: [0, 0]) even when the base path uses the rounded [0.5, 0.5] default. Set connection.endcapExtension to round it.
mapView.Navigation.draw(directions, {
pathOptions: {
color: '#40A9FF',
connection: {
geometry: 'ribbon',
color: '#722ED1',
dash: { enabled: true },
},
},
});
The following image shows a map with multi-floor wayfinding using the Navigation class.

Multi-Destination Wayfinding
Multi-segment directions are directions that include multiple legs. They can be created by passing an array of destinations to MapViewControl.getDirectionsMultiDestination.
A complete example demonstrating multi destination directions can be found in the Mappedin React Native GitHub repo: directions-multi-destination.tsx
The following image shows a map with multi-destination wayfinding using the Navigation class.

// Pass an array of destinations to create multi-segment directions.
const directions = await mapData.getDirectionsMultiDestination(departure, destinations);
Wayfinding Using Accessible Routes
When requesting directions, it is important to consider the needs of the user. Users with mobility restrictions may require a route that avoids stairs and escalators and instead uses ramps or elevators.
The getDirections method accepts Mappedin.TGetDirectionsOptions, which allows specifying whether an accessible route should be returned. By default, the shortest available route is chosen. The following code demonstrates how to request directions that make use of accessible routes.
const directions = await mapData.getDirections(space1, space2, { accessible: true });
Drawing a Path
While Navigation provides a complete start and end navigation illustration, it may be desired to draw just the path. This can be done using Paths.
A complete example demonstrating paths can be found in the Mappedin React Native GitHub repo: paths.tsx
Note that the MapViewControl class implements the Mappedin.Paths interface and exposes it as MapViewControl.Paths. Use MapViewControl.Paths to utilize Mappedin.Paths methods.
Paths can be drawn from one coordinate to another using Mappedin.Paths.add(). If using just two coordinates, the path will be drawn straight between the two points. This may work for some scenarios, but in most cases an app will need to show the user their walking path, going through doors and avoiding walls and other objects. Such a path of coordinates can be created by calling the MapViewControl.getDirections()method, passing in a start and end Mappedin.TNavigationTarget. Note that a Mappedin.Space requires an entrance to be used as a target.
The following image shows a map with a path drawn between two spaces.

The width of the path is set using the width parameter. This value is in meters. Additional path styles are outlined later in this guide in the Path Styles section.
- Declarative
- Imperative
// Get the directions between two spaces.
const directions = await mapData.getDirections(startSpace, endSpace);
Then use the directions to draw a path.
{
directions && directions.coordinates && (
<Path
key="navigation-path"
coordinate={directions.coordinates}
options={{
color: '#007AFF',
width: 0.5,
interactive: true,
}}
onLoad={path => {
console.log('Path loaded successfully:', path.id);
console.log('Path coordinates count:', path.coordinates?.length);
}}
onDrawComplete={() => {
console.log('Path drawing animation completed');
}}
/>
);
}
// Get the directions between two spaces.
const directions = await mapData.getDirections(startSpace, endSpace);
// Draw a path using the directions' coordinates array to show the route.
path = await mapView.Paths.add(directions.coordinates, {
width: 0.5,
});
Removing Paths
There are two methods that can be used to remove paths. Mappedin.Paths.remove() accepts a path to remove and is used to remove a single path. To remove all paths, Mappedin.Paths.removeAll() can be used.
// Remove a single path.
mapView.Paths.remove(path);
// Remove all paths
mapView.Paths.removeAll();
Path Styles
Paths.add() and Navigation.draw() both accept Mappedin.TAddPathOptions. color, width (meters), displayArrowsOnPath, and animateArrowsOnPath cover the common cases. The options below control geometry, corner rounding, dashes, and how a path looks behind walls and floors. The same options object is passed to the declarative <Path options={...} /> component.
Geometry
geometry selects the mesh. 'tube' (the default) is a round extruded path. 'ribbon' is a flat ribbon and is required for endcapExtension, billboarding, border, screen-space width values such as '20px', and the discrete dash style.
endcapExtension is a [start, end] tuple in meters (default [0.5, 0.5]). A value above 0 extends the path and draws a rounded cap; 0 ends the path square.
billboarding controls whether a ribbon faces the camera. true billboards every vertex, false keeps the ribbon flat in world space, and a number from 0 to 90 is a threshold in degrees — the default 80 billboards only near-vertical segments, such as a connection between floors.
border draws an edge along both sides of a ribbon: { enabled: true, color: 'darken' }. color accepts 'darken' or a CSS colour string. width is a fraction of the ribbon width from 0 to 0.5, default 0.1.
Corner Rounding
smoothing rounds the corners of a drawn path. It takes tension (default 0) and cornerRadius in meters (default 0.5). tension between 0.1 and 0.3 gives a subtle curve. This is visual only and does not change the route — route simplification is covered under Route Simplification.
Dashed Paths
dash breaks a path into dashes. enabled turns dashing on (default false). The dash shape follows geometry: a ribbon draws each dash as its own rounded rectangle that holds its shape around corners, while a tube paints the dash pattern onto one continuous path.
mode selects the sizing, and defaults to 'width-scaling':
| Mode | Sizing fields | Units | Defaults |
|---|---|---|---|
'width-scaling' | size, gapSize | Multiples of the path width | 1.2, 0.6 |
'absolute' | meters, gapMeters | Meters | 1.0, 0.5 |
'length-scaling' | length, gap | Fraction of the path length, 0 to 1 | 0.1, 0.1 |
dash.cornerRadius rounds each dash from 0 (square) to 1 (fully round) and applies to ribbon geometry only.
mapView.Paths.add(directions.coordinates, {
width: 1.5,
geometry: 'ribbon',
smoothing: { tension: 0.15, cornerRadius: 0.5 },
border: { enabled: true, color: 'darken' },
endcapExtension: [0.5, 0.5],
dash: { enabled: true, mode: 'width-scaling', size: 1.2, gapSize: 0.6 },
});
Rendering Behind Geometry
xray controls how a path appears when it passes behind geometry such as a wall or another floor. opacity (0 to 1, default 0.25) sets the strength, tint (0 to 1, default 0.3) mutes the colour, color overrides the computed colour, and dithering sets a checkerboard cell size in screen pixels (0 or omitted disables it).
mapView.Paths.add(directions.coordinates, {
xray: { opacity: 0.25, tint: 0.3, dithering: 2 },
});
Dynamic Routing
When generating directions, Mappedin SDK for React Native provides the most direct route possible between the origin and destination. There can be scenarios when this is not desired, such as when there there is an obstruction like a spill that requires cleaning or where maintenance crews are active.
The MapViewControl.getDirections() method accepts a zones parameter that denotes areas that could be avoided. Zones are defined using Mappedin.TDirectionZone and contain a cost, floor and geometry.
cost represents the additional cost for navigation through the zone and can range from from 0 to Infinity. A cost of 0 will make the zone free to navigate through. A zone cost of Infinity will block passage through the zone. Multiple zones occupying the same location they are added together, along with the cost from the map. The SDK may route directions through a zone if all other routes have a higher cost.
floor represents the floor for the zone. If not specified the zone blocks all floors.
geometry is held within a Mappedin.Feature that contains a Mappedin.MultiPolygon or Mappedin.Polygon.
Turn-by-Turn Directions
Turn-by-Turn directions are a set of text instructions describing the route the user needs to take. An example is "Turn right and go 10 meters". These could be shown to the user in a list to give them an overview with all steps they need to take, or the current instruction could be displayed along with a map showing the next leg of their journey.
The following image shows a map with turn-by-turn directions.

The code sample assembles these actions together and:
- Gets directions between the start and end Mappedin.TNavigationTarget.
- Draws a path using the directions' coordinates.
- Creates a Mappedin.Marker with textual turn-by-turn instructions for each leg in the journey. Refer to the Marker Guide for more information on using Markers.
- Declarative
- Imperative
// Get directions from the first space to the second space.
const directions = await mapData.getDirections(firstSpace, secondSpace);
Then use the directions to draw a path and add markers for each direction instruction.
{
directions && (
<>
<Path key="navigation-path" coordinate={directions.coordinates} />
{directions.instructions.map((instruction, directionIndex) => (
<Marker
key={`${directions.id}-${directionIndex}`}
target={instruction.coordinate}
html={`
<div class="marker">
<p>${instruction.action.type} ${instruction.action.bearing ?? ''}
in ${Math.round(instruction.distance)} meters.</p>
</div>`}
/>
))}
</>
);
}
// Get directions from the first space to the second space.
const directions = await mapData.getDirections(firstSpace, secondSpace);
// Add a path from the first space to the second space.
mapView.Paths.add(directions.coordinates);
// Add markers for each direction instruction.
directions.instructions.forEach((instruction: TDirectionInstruction) => {
const markerTemplate = `
<div class="marker">
<p>${instruction.action.type} ${instruction.action.bearing ?? ''} in ${Math.round(
instruction.distance
)} meters.</p>
</div>`;
mapView.Markers.add(instruction.coordinate, markerTemplate,
{
rank: 4,
});
});