## version-6.0

### 3D Models

# 3D Models

> 

> 

!3D Model Mapper

## Adding 3D Models to a Map

Adding 3D models to a map can be a great way to represent landmarks to help users find key locations. They could also be used to show the location of assets or represent furniture to provide a rich indoor layout.

Mappedin SDK for React Native supports models in Graphics Library Transmission Format (GLTF) and GL Transmission Format Binary (GLB) format. Models with nested meshes are not supported and should not be used.

> A complete example demonstrating 3D models can be found in the Mappedin React Native Github repo: models.tsx

3D Models can be added to the map using the MapViewControl.Models.add() method. The `add` method requires a Mappedin.Coordinate to place the model and a URL of the model file. Optionally, the model's interactivity, rotation, scale and more can also be set using the `options` parameter, which accepts a Mappedin.TAddModelOptions. Models can be updated by calling the MapViewControl.updateState() method.

The following code samples demonstrate adding a 3D model to the map.


  

```tsx
<Model
  target={coordinate}
  options={{
    scale: 2,
    rotation: [0, 0, 90],
    opacity: 1,
  }}
  url={"https://yourDomain.com/models/yourModel.glb"}
/>
```




```ts
mapView.Models.add(coordinate, 'https://yourDomain.com/models/yourModel.glb', {
    interactive: true,
    rotation: [0, 0, 90],
    scale: [10, 10, 10],
});
```




## Mappedin 3D Model Library

The Mappedin 3D Assets Library is a collection of 3D models that can be used to represent landmarks, assets, and furniture on a map. It is optimized for use with Mappedin SDKs. These models are used in the 3D Model Mapper tool, which allows you to place models on a map and customize their appearance.

### Installation

The Mappedin 3D Assets Library is available as an npm package available at https://www.npmjs.com/package/@mappedin/3d-assets. It can be installed using the following commands:

**NPM**:


```bash
npm install @mappedin/3d-assets
```


**Yarn**:


```bash
yarn add @mappedin/3d-assets
```


### Usage

This package provides two ways to use the 3D assets:

1. Self-hosted GLB files (Recommended).
2. Direct base64 model imports.

#### Self-hosted GLB files (Recommended)

The `/binary` directory contains GLB files that can be self hosted on your own server. This method is recommended as it provides:

-   30% smaller download size
-   No runtime overhead
-   Better caching control


```ts
// Example usage with self-hosted GLB
const coordinate = mapView.createCoordinate(45, -75);
mapView.Models.add(coordinate, 'https://your-domain.com/assets/model.glb');
```


#### Direct Base64 Imports

For convenience, models can be imported directly as base64 strings. This method is easier to set up but comes with a larger bundle size.


```ts
// Import specific models (supports tree-shaking)
import { bed, chair } from '@mappedin/3d-assets/inline';

// Or import individual models
import plant from '@mappedin/3d-assets/inline/plant_1';

// Usage with MapView
const coordinate = mapView.createCoordinate(45, -75);
mapView.Models.add(coordinate, bed);
```


This package supports tree-shaking when using direct imports. Only models explicitly imported will be included in the final bundle.


```ts
// Only the bed model will be included in the bundle
import { bed } from '@mappedin/3d-assets/inline';
```


### Example

The 3D Model Mapper can be used to place models from the Mappedin 3D Assets Library on a map. Once placed, the model's location details can be exported to a JSON file that can be used when adding models to a map in an app. The Using the 3D Model Export In Other Projects section contains an interactive example that demonstrates using the exported JSON file to add 3D models.

### Model List

The Mappedin 3D Assets Library contains the following models. Each model's default blue color can be customized when adding it to the map.


    
        
            
                
                
                Bathtub
            
            
                
                
                Bed
            
            
                
                
                Bookshelf
            
            
                
                
                Box Cardboard
            
        
        
            
                
                
                Can Garbage
            
            
                
                
                Can Recycling
            
            
                
                
                Car
            
            
                
                
                Chair
            
        
        
            
                
                
                Computer
            
            
                
                
                Couch
            
            
                
                
                Couch Curved
            
            
                
                
                Couch Outward Curve
            
        
        
            
                
                
                Desk
            
            
                
                
                Desk Chair
            
            
                
                
                Dryer
            
            
                
                
                EV Charger
            
        
        
            
                
                
                Floor Lamp
            
            
                
                
                Fountain
            
            
                
                
                High Bench
            
            
                
                
                Hot Tub
            
        
        
            
                
                
                Kitchen Sink
            
            
                
                
                Kiosk
            
            
                
                
                Plant 1
            
            
                
                
                Plant 2
            
        
        
            
                
                
                Privacy Booth
            
            
                
                
                Refrigerator
            
            
                
                
                Round Table
            
            
                
                
                Self Checkout
            
        
        
            
                
                
                Shipping Container
            
            
                
                
                Shopping Shelves
            
            
                
                
                Stove
            
            
                
                
                Toilet
            
        
        
            
                
                
                Tree Pine
            
            
                
                
                Tree Pine Short
            
            
                
                
                Truck
            
            
                
                
                TV
            
        
        
            
                
                
                Vending Machine
            
            
                
                
                Washer
            
            
                
                
                Whiteboard
            
            
                
                
                Wood Stove

### Annotations

# Annotations

> 

> 

Map annotations add visual or textual elements to maps, providing extra information about specific locations or features. Map makers can choose from many annotations included in the Mappedin Editor to add to a map and access them using Mappedin SDK for React Native. Mappedin.Annotations are organized into the following groups.

> Note that these are just a few examples of annotations, each group contains many more.

| Annotation Group  | Examples                                     |
| ----------------- | -------------------------------------------- |
| Access Features   | Keybox, roof access                          |
| Building Sides    | Alpha, bravo, charlie, delta                 |
| Equipment Rooms   | Boiler Room, Sprinkler control room          |
| Fire Ratings      | Fire and smoke wall 1 hour, firewall 3 hours |
| Fire Safety       | Fire Blanket, Fire Hose Reel                 |
| General Systems   | Emergency Generator, Smoke Control Panel     |
| Hazards           | Biohazard, Explosive                         |
| Safety            | Accessible Elevator, Eyewash Station         |
| Utility Shutoff   | Gas Valve, Main Water Valve                  |
| Ventilation       | Chimney, Exhaust Fan                         |
| Water Connections | Sprinkler FDC, Public Hydrant                |
| Water Systems     | Fire Pump, Pressurized Water Tank            |

Incorporating annotations help provide a safer space for all. It allows users to easily locate key elements in the map.

!Mappedin JS v6 Annotations

## Using Annotations

The following code sample lists each Annotation.type in text form that exist on the Mappedin Demo Office Map. It reads the annotations from each floor and groups them by their Annotation.group.


```ts
// Sort the floors alphabetically.
const sortedFloors = mapData
  .getByType("floor")
  .sort((a, b) => (a.name > b.name ? 1 : b.name > a.name ? -1 : 0));

// Iterate through each floor and create a list of annotations.
sortedFloors.forEach((floor) => {
  // Use the floor name as the heading.
  console.log("Floor Name: " + floor.name + " Annotations");

  // Sort the annotation groups alphabetically.
  const sortedAnnotations = floor.annotations.sort((a, b) =>
    a.group > b.group ? 1 : b.group > a.group ? -1 : 0
  );

  var annotationGroup = "";

  // Iterate through each annotation and create a list of annotations.
  sortedAnnotations.forEach((annotation) => {
    // If the annotation group changes, log the new group name.
    if (annotationGroup != annotation.group) {
      annotationGroup = annotation.group;
      console.log("Annotation Group: " + annotation.group);
    }

    // Log each annotation.
    console.log("Annotation: " + annotation.type);
  });
});
```


The output of the code sample will be similar to the following:


```
Floor Name: Level 1 Annotations
Annotation Group: access-features
Annotation: keybox
Annotation: primary-entrance
Annotation Group: equipment-rooms
Annotation: electrical-transformer-room
Annotation Group: fire-safety
Annotation: fire-alarm-pull-station
Annotation: fire-emergency-phone
Annotation Group: general-systems
Annotation: fire-alarm-annunciator-panel
Annotation Group: safety
Annotation: evacuation-chair
Annotation Group: utility-shutoffs
Annotation: gas-valve-general
Annotation: main-water-valve
Annotation Group: water-connections
Annotation: fdc-general
Floor Name: Level 2 Annotations
Annotation: elevator-firefighter
Annotation: fire-extinguisher
```


## Annotation Icons

The Mappedin Editor and Viewer use a set of SVG icons to represent annotations. The CodeSandbox below demonstrates using these icons and placing them as Markers on the map. The `annotation-icons.ts` file in the example contains an array with all icon ids, category, uri and SVG image.

### API Reference

# API Reference
## Latest Version


Mappedin SDK for React Native v6.0.0-beta.1





## Previous Versions


v6.0.0-beta.0v6.0.0-alpha.14v6.0.0-alpha.13v6.0.0-alpha.12

### Areas & Shapes

# Areas & Shapes

> 

> 

## Areas

An Mappedin.Area represents a logical region on the map. They do not represent a physical attribute like a wall or desk, but rather a region that can be used to trigger events, display information, or affect wayfinding. An area is made up of a polygon stored as a GeoJSON Mappedin.Feature, which can be accessed using Mappedin.Area.geoJSON. The Mappedin.Feature can be passed to other methods in Mappedin JS.

Mappedin.Shapes.add() accepts an FeatureCollection and can be used to display one or more areas on the map. The code snippet below demonstrates how to use an `Area` to create a `Shape` and add it to the map.


```ts
// Get the first area.
const areas = mapData.getByType('area');
const areaGeoJSON = areas[0].geoJSON;

// Create a FeatureCollection containing the Feature of the Area.
const shapeFeatureCollection = {
    type: 'FeatureCollection',
    features: [
        {
            type: areaGeoJSON.type,
            properties: areaGeoJSON.properties,
            geometry: areaGeoJSON.geometry,
        },
    ],
};

// Draw a shape of the area.
mapView.Shapes.add(shapeFeatureCollection, {
    color: 'orange',
    altitude: 0.2,
    height: 0.1,
    opacity: 0.7,
});
```


Within the Mappedin Editor, it is possible to create an area and set it to be off limits for wayfinding. This means that the area will be excluded from the route calculation and directions will be rerouted around the area. This is useful for creating areas that are permanently off limits.

The following image shows how a path has been routed around areas that are set to not be navigable.

!Path routed around areas that are set to not be navigable

At runtime, it is also possible to use an area as an exclusion zone for wayfinding. This is useful for creating areas that are temporarily off limits. Below is a code snippet that demonstrates how to use an `Area` to define a region that a wayfinding route should avoid at runtime. Refer to the Dynamic Routing section of the Wayfinding Guide for an interactive example that demonstrates clicking to set an exclusion zone.

Mappedin.TDirectionZone is the type of the Mappedin.TGetDirectionsOptions.zones property that is passed to MapViewControl.getDirections, MapViewControl.getDirectionsMultiDestination() and MapViewControl.getDistance(). These zones can be used to affect the route calculation by excluding a polygon from the route.

The following code snippet demonstrates how to use an `Area` to define a region that a wayfinding route should avoid.


```ts
//Get all areas.
const areas = mapData.getByType('area');

// Get the maintenance area.
const maintenanceArea = areas.find((area: any) => area.name === 'Maintenance Area');
const maintenanceGeoJSON = maintenanceArea.geoJSON;

// Create directions that route around the area.
const origin = mapData.getByType('object').find(obj => obj.name === 'I3');
const destination = mapData.getByType('door').find(obj => obj.name === 'Outbound Shipments 1');

if (origin && destination && shapeFeatureCollection) {
    const zoneFeature = {
        type: maintenanceGeoJSON.type,
        properties: maintenanceGeoJSON.properties,
        geometry: maintenanceGeoJSON.geometry,
    };
    let zones = [];
    zones.push({
        geometry: zoneFeature as Feature<Polygon>,
        cost: Infinity,
        floor: mapView.currentFloor,
    });
    const directions = mapView.getDirections(origin, destination, { zones });

    if (directions) {
        await mapView.Paths.add(directions.coordinates, {
            color: 'cornflowerblue',
        });
    }
}
```


## Shapes

The Mappedin.Shapes class draws 3 dimensional shapes on top of a map. The shapes are created using GeoJSON geometry, which could be a Mappedin.Polygon, Mappedin.MultiPolygon (array of polygons) or a Mappedin.LineString.

The following image shows a map with a shape drawn on top of it.

!Map with a shape drawn on top of it

> A complete example demonstrating shapes can be found in the Mappedin React Native Github repo: shapes.tsx

Access the Shapes interface through MapViewControl using MapViewControl.Shapes. Shapes are added by calling Mappedin.Shapes.add() and removed individually by calling Mappedin.Shapes.remove() and passing in the Mappedin.Shape object to be removed. All shapes can be removed at once by calling Mappedin.Shapes.removeAll().

The following code example adds a shape after the map is first loaded. Clicking on the map removes a shape if one is present and if not, adds the shape back to the map.


```ts
let shape: =
  mapView.Shapes.add(shapeGeometry as any, {
    color: "red",
    altitude: 0.2,
    height: 2,
    opacity: 0.7,
  });

mapView.on("click", async (event) => {
  if (shape) {
    mapView.Shapes.remove(shape);
    shape = undefined;
  } else {
    shape = mapView.Shapes.add(shapeGeometry as any, {
      color: "red",
      altitude: 0.2,
      height: 2,
      opacity: 0.7,
    });
  }
});
```


Refer to the Security Camera Placement example in the Developer Showcase for a more advanced example that uses shapes to draw the field of view of security cameras.

### Blue Dot

# Blue Dot

> 

> 

The Blue Dot is a visual marker in mapping apps that shows a user's real-time location. It serves as a reference point, helping users identify their position and navigate efficiently. GPS, Wi-Fi, or other tracking technologies typically power the Blue Dot to ensure location accuracy. Mappedin JS provides a simple way to add a Blue Dot to a map.

!Blue Dot

## Installation

Blue Dot functionality is provided as a separate package that works in conjunction with Mappedin JS. To install the `@mappedin/blue-dot` package from npm, run the following command:

With NPM:


```bash
npm install @mappedin/blue-dot
```


With Yarn:


```bash
yarn add @mappedin/blue-dot
```



## Enable & Disable Blue Dot

With the `@mappedin/blue-dot`  package, an app can display a user's location by creating a new BlueDot instance and calling its `enable()` method. This will display a prompt for the user to allow or deny sharing their location with the web page. If permission is given, a device's geolocation is displayed on the map as a Blue Dot. The `enable` method accepts a `BlueDotOptions` object as a parameter, which can be used to change the color of the Blue Dot, accuracy shading and heading indicator. It also allows a developer to enable Blue Dot debug logging, set the size of the Blue Dot, indicate whether it should watch the browser's geolocation for updates and to set the timeout value used to set the Blue Dot to inactive after a period of no location updates.

When no longer required, the Blue Dot can be disabled using the `disable()` method.

The following example demonstrates how to enable the Blue Dot, setting `BlueDotOptions` parameters to customize the color of the Blue Dot, set its radius and disable `watchDevicePosition`.


```tsx
import React, { useEffect, useCallback } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { MapView, useMapData } from '@mappedin/react-native-sdk';
import { useBlueDot, useBlueDotEvent } from '@mappedin/blue-dot/rn';

function MyComponent() {
	const { mapData } = useMapData({
		key: 'your-api-key',
		secret: 'your-api-secret',
		mapId: 'your-map-id',
	});

	return (
		<MapView mapData={mapData}>
			<BlueDotDisplay />
		</MapView>
	);
}

function BlueDotDisplay() {
	// All methods are async and return Promises
	const {
		isReady,
		isEnabled,
		state,
		position,
		floor,
		following,
		accuracy,
		heading,
		enable,
		disable,
		update,
		follow,
		unfollow
	} = useBlueDot();

	// Listen for position updates
	useBlueDotEvent('position-update', useCallback((event) => {
		console.log('Position updated:', event.coordinate, event.floor);
	}, []));

	// Listen for state changes
	useBlueDotEvent('state-change', useCallback((event) => {
		console.log('State changed:', event.state);
	}, []));

	// Listen for follow mode changes
	useBlueDotEvent('follow-change', useCallback((event) => {
		console.log('Follow mode:', event.following);
	}, []));

	useEffect(() => {
		if (isReady && !isEnabled) {
			// All methods are async - use await or .then()
			enable({
				radius: 15,
				color: '#ff0000',
				watchDevicePosition: false
			});
		}
	}, [isReady, isEnabled, enable]);

	const handleUpdatePosition = useCallback(async () => {
		try {
			// Update position manually
			await update({
				latitude: 43.6532,
				longitude: -79.3832,
				accuracy: 5,
				heading: 90,
				floorOrFloorId: floor
			});

			// Enable follow mode
			await follow('position-and-heading', {
				zoomLevel: 19
			});
		} catch (error) {
			console.error('Failed to update position:', error);
		}
	}, [update, follow, floor]);

	return (
		<View>
			<Text>Is Ready: {isReady ? 'Yes' : 'No'}</Text>
			<Text>Is Enabled: {isEnabled ? 'Yes' : 'No'}</Text>
			<Text>State: {state}</Text>
			<Text>Following: {following ? 'Yes' : 'No'}</Text>
			{position && (
				<Text>Position: {position.latitude.toFixed(4)}, {position.longitude.toFixed(4)}</Text>
			)}
			{accuracy && <Text>Accuracy: {accuracy.toFixed(1)}m</Text>}
			{heading && <Text>Heading: {heading.toFixed(0)}°</Text>}
			<TouchableOpacity onPress={handleUpdatePosition}>
				<Text>Update Position & Follow</Text>
			</TouchableOpacity>
		</View>
	);
}
```


## States

The Blue Dot has a number of visual states that are used to convey information to the user.

-   When the Blue Dot position given to Mappedin JS has a high accuracy (accuracy value of 0), it is displayed as bright blue.

    !Blue Dot

-   A semi-transparent blue shadow is displayed underneath the Blue Dot to indicate accuracy range in meters.

    !Blue Dot Accuracy Range

-   A heading can be shown to indicate the direction the user is facing.

    !Blue Dot Heading

-   After the `BlueDotOptions.timeout` has passed (default of 30 seconds), the Blue Dot is displayed as greyed. This indicates the user may have moved while no updates were received.

    !Blue Dot Timeout

## Follow Mode

A user may pan the camera away and lose track of their Blue Dot position. An app may want to snap the camera to the user's location to reorient themselves. While this could be done using camera focus on, an app can also leverage Blue Dot's follow mode. Follow mode has multiple modes that are defined within `FollowMode`, which are:

-   `position-only`: Camera position follows the Blue Dot's position.
-   `position-and-heading`: Camera position follows the Blue Dot's position. Camera bearing matches the Blue Dot's heading.
-   `position-and-path-direction`: Camera position follows the Blue Dot's position. Camera bearing is calculated based on the Navigation path.
-   `false`: Disables follow mode.

Example:


```ts
blueDot.follow('position-only');
```


## Indoor Positioning

Mappedin SDK for React Native can use the browser's Geolocation API for position updates and display a Blue Dot on the map based on the given location. For indoor environments, an indoor positioning system may be required to provide an accurate location because satellite based positioning is not available indoors and cellular based positioning may not be accurate enough for indoor navigation.

Mappedin SDK for React Native can use the location provided from an indoor positioning system to display the Blue Dot. An example of an indoor positioning system is the Apple Maps Program, which provides a location service for indoor use. A Mappedin Map can be exported to IMDF format and imported into the Apple Maps Program. For more information refer to the Mappedin IMDF Export Page.

For development purposes, indoor positions can be simulated using Chrome Developer Tools or by using pre-generated location data. The MapViewControl.BlueDot.update() method can be used to update the Blue Dot's position on the map. It accepts a Mappedin.TBlueDotPositionUpdate that can set the `latitude`, `longitude`, `accuracy` `heading` and `floorOrFloorId` of the Blue Dot. All parameters of `TBlueDotPositionUpdate` are required, however it is possible to set individual parameters to override one or more coming from the browser's geolocation API. To do so provide values for parameters the app wishes to override and use `device` as the value of those parameters that should not be overridden. For example an app may wish to use the browser's Device Orientation API to provide the heading of the Blue Dot and leave the latitude and longitude to be provided by the browser's geolocation API.

The following JSON object represents a `BlueDotPositionUpdates` that overrides `heading` and uses the browser's geolocation API for the remaining parameters.


```JSON
{
  "accuracy": 'device',
  "floorOrFloorId": 'device',
  "latitude": 'device',
  "longitude": 'device',
  "heading": 90
}
```


## Events

Blue Dot fires events that can be used to respond to changes to its position, state and errors. The following events are available:

-   `error`: Fired when an error occurs.
-   `follow-change`: Fired when the Blue Dot's follow mode changes.
-   `position-update`: Fired when Blue Dot's position is updated.
-   `state-change`: Fired when Blue Dot's state changes.

### Blue Dot Position Update

The `position-update` event is fired when the Blue Dot's position is updated. It provides the coordinate, floor, accuracy and heading from the last position update.


```ts
// Listen for position updates
useBlueDotEvent('position-update', useCallback((event) => {
  console.log('Position updated:', event.coordinate, event.floor);
}, []));
```


### Blue Dot State Change

The `state-change` event is fired when Blue Dot state changes. It provides the new state of the Blue Dot and the action that caused the state change. The states pertain to how the Blue Dot is displayed on the map. Refer to the Blue Dot States section above for images of each state.


```ts
	// Listen for state changes
	useBlueDotEvent('state-change', useCallback((event) => {
		console.log('State changed:', event.state);
	}, []));
```


### Blue Dot Error

The `error` event is fired when an error occurs. It provides the error as a GeolocationPositionError object.


```ts
	// Listen for errors
	useBlueDotEvent('error', useCallback((error) => {
		console.log('Error:', error);
	}, []));
```


## Generating Test Location Data

The Mappedin Blue Dot Location Generator can be used to generate location data for testing. To create test data, load a map in the generator app and choose a Start and End space. Click Generate to generate the data and observe the Blue Dot on the map using the generated data for its position. Press the Download button to download the location data in JSON format. The data can be customized by specifying the parameters below:

-   **Venue Settings**: Add in a key, secret and map ID to load a different map.
-   **Environment**: Whether to load the map from Mappedin's North American or European environment. By default, maps exist in the North American environment.
-   **Jitter**: The amount of random variation in the position data from the navigation path.
-   **Accuracy**: The accuracy used in the data. In a real world scenario this value represents how accurate the indoor positioning system believes the result to be and is used to draw the light blue shading around the Blue Dot.
-   **Distance Between Updates**: The physical distance between each position update. Lower values will result in smoother movement of the Blue Dot.
-   **Start Space**: The space to start the Blue Dot's movement.
-   **End Space**: The space to end the Blue Dot's movement.
-   **Time between updates**: The time between each position update can be used to control the speed of the Blue Dot's movements.
-   **Path Width**: Controls the size of the path shown on the map.

### Blue Dot Location Generator

### Building & Floor Selection

# Building & Floor Selection

> 

> 

## Floor Selection

When mapping a building with multiple floors, each floor has its own unique map. These are represented by the Mappedin.Floor class, which are accessed using Mappedin.MapData.getByType('floor'). The currently displayed Floor can be accessed using MapViewControl.currentFloor.

!Mappedin-Web-SDK-v6-Level-Selector

### Changing Floors

When initialized, MapView displays the Mappedin.Floor with the elevation that's closest to 0. This can be overridden by setting Mappedin.TShow3DMapOptions.initialFloor to a Mappedin.Floor or Mappedin.Floor.id and using it in the MapViewProps.


  

```tsx
<MapView
  options={{
    initialFloor: 'm_123456789',
  }}
  mapData={{
    key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
    secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
    mapId: "660c0c3aae0596d87766f2da",
  }}
>
</MapView>
```




```ts
// Setting the initial floor to Floor.id 'm_123456789'.
const mapView = await show3dMap(
    document.getElementById('mappedin-map') as HTMLDivElement,
    mapData,
    {
        initialFloor: 'm_123456789',
    }
);
```




The Mappedin.Floor displayed in a MapView can also be changed during runtime by calling MapViewControl.setFloor() and passing in a Mappedin.Floor or Mappedin.Floor.id.


```ts
// Set the floor to Floor.id 'm_987654321'.
mapView.setFloor(`m_987654321`);
```


### Listening for Floor Changes

The Mappedin event system provides the ability to listen for floor changes on a MapView. The code below listens for the `floor-change` event and logs the new floor name to the console.


```tsx
useMapViewEvent("floor-change", (event) => {
console.log(
  "Floor changed to:",
  event?.floor.name,
  "in FloorStack:",
  event?.floor.floorStack.name
);
});
```


## Building Selection

Mappedin Maps can contain one to many buildings with each building having one to many floors. Each building has its floors organized into a Mappedin.FloorStack object. When multiple buildings are present, there are multiple Mappedin.FloorStack objects, one for each building. A Mappedin. FloorStack contains one to many Mappedin.Floor objects, each representing the map of each level of the building.

The Mappedin.FloorStack object is accessed by using MapData.getByType('floor-stack').


```ts
// Get the FloorStack object.
const floorStacks = mapData.getByType('floor-stack');
```

### Camera

# Camera

> 

> 

Controlling the view of the map allows apps to create visually rich experiences using Mappedin SDK for React Native. This guide shows how to focus the map view on targets, move the camera and listen to camera events.

!Mappedin JS v6 Camera

> Note that the **MapViewControl** class implements the **Mappedin.Camera** interface and exposes it as **MapViewControl.Camera**. Use **MapViewControl.Camera** to utilize **Mappedin.Camera**'s methods.

## Focus the Camera on Targets

Mappedin JS has built in functionality to focus the camera on one ore more targets using a single or array of Mappedin.IFocusable. When multiple targets are used, the SDK will ensure that all targets are visible.

The following sample code acts on the click event to focus on the Mappedin.Space the user clicked on. Note that the Mappedin.Space must be set to interactive to allow it to be clickable. Refer to the Interactivity guide for more information on how to set a space to interactive.


```ts
// Act on the click event to focus on the Space that was clicked.
useMapViewEvent('click', async (event: Mappedin.TClickPayload;) => {
	// Focus on the space that was clicked.
	mapView.Camera.focusOn(event.spaces[0]);
});
```


## Controlling the Camera

To control the camera, set it with new pitch, bearing or zoom using MapViewControl.Camera.set(). It accepts a Mappedin.TCameraTarget object that contains bearing, center coordinate, pitch and zoom level. These parameters are all optional, allowing the camera to by moved by adjusting one or more of these values.

### TCameraTarget

-   **bearing:** Bearing for the camera target in degrees.
-   **center:** Center `Coordinate` for the camera target.
-   **pitch:** Pitch for the camera target in degrees.
-   **zoomLevel:** Zoom level for the camera target in mercator zoom levels.


```ts
mapView.Camera.set({
	bearing: 30,
	pitch: 80,
	zoomLevel: 19.5,
	center: e.coordinate,
});
```


## Animation

The camera can also be animated into position using the same transforms described in the Controlling the Camera section above. This is done using the MapViewControl.Camera.animateTo() method. Similar to MapViewControl.Camera.set(), the `animateTo` method accepts a Mappedin.TCameraTarget object, but it is optional. This allows the camera to changed by adjusting its `bearing`, `pitch` or `zoomLevel` without specifying a new target to move to. In addition, `animateTo` also accepts Mappedin.TCameraAnimationOptions that allow setting of the duration of the animation in milliseconds and setting the easing curve.

The next code snippet acts on the click event to animate the camera to the click position. It uses easing `ease-in-out` over 4000 milliseconds.


```ts
// Act on the click event to animate to a new camera position.
useMapViewEvent('click', async (event: Mappedin.TClickPayload) => {
	mapView.Camera.animateTo(
		{
			bearing: 30,
			pitch: 80,
			zoomLevel: 18,
			center: event.coordinate,
		},
		{ duration: 4000, easing: 'ease-in-out' },
	);
});
```


The types of easing anmiations are defined in Mappedin.TEasingFunction.

### TEasingFunction

-   **Linear:** This function implies a constant rate of change. It means the animation proceeds at the same speed from start to end. There's no acceleration or deceleration, giving a very mechanical feel.
-   **Ease-in:** This function causes the animation to start slowly and then speed up as it progresses. Initially, there's gradual acceleration, and as the function moves forward, the rate of change increases.
-   **Ease-out:** Contrary to ease-in, ease-out makes the animation start quickly and then slow down towards the end. It begins with a faster rate of change and gradually decelerates.
-   **Ease-in-out:** This function combines both ease-in and ease-out. The animation starts slowly, speeds up in the middle, and then slows down again towards the end. It offers a balance of acceleration and deceleration.

## Resetting The Camera

While there is no method in Mappedin SDK for React Native to reset the camera to its default position, this can be easily built into an app. To do so, store the camera position after the map is shown and then use those values to reposition the camera at a later time.

The code sample below stores the initial camera position. When a user clicks on a location it first focuses on that space. The next click will return the camera to its original position.


```ts
let focused: boolean = false;

const defaultCameraPosition: TCameraTarget = {
	bearing: mapView.Camera.bearing,
	pitch: mapView.Camera.pitch,
	zoomLevel: mapView.Camera.zoomLevel,
	center: mapView.Camera.center,
};

// Set each space to be interactive and its hover color to orange.
mapData.getByType('space').forEach((space) => {
	mapView.updateState(space, {
		interactive: true,
		hoverColor: '#4248FF',
	});
});

// Act on the click event to focus on the Space that was clicked or reset the camera.
useMapViewEvent('click', async (event: Mappedin.TClickPayload) => {
	if (focused) {
		// Reset the camera to its default position.
		mapView.Camera.set(defaultCameraPosition);
		focused = false;
	} else {
		// Focus on the space that was clicked.
		mapView.Camera.focusOn(event.spaces[0]);
		focused = true;
	}
});
```


## Listening to Camera Events

There are several camera events that can be acted on by setting a listener with useMapViewEvent('camera-change'). The camera-change event contains a Mappedin.CameraTransform object. Mappedin.CameraTransform provides the bearing, center coordinate, pitch and zoom level.


```ts
// Log camera change events to the console.
useMapViewEvent('camera-change', async (cam: Mappedin.CameraTransform) => {
	console.log(
		'Bearing: ' +
			cam.bearing +
			', Pitch: ' +
			cam.pitch +
			', Zoom Level: ' +
			cam.zoomLevel +
			', Center: Lat:' +
			cam.center.latitude,
		+', Lon:' + cam.center.longitude,
	);
});
```

### Connections

# Connections

> 

> 

Map connections are pathways in multi-floor and multi-building maps that enable vertical or horizontal movement between levels, spaces or buildings. They include stairs, elevators, and escalators, providing essential links for seamless navigation and spatial continuity across the map. The Mappedin.Connection includes details such as name, description, floors, coordinates and more.

Mappedin.Connection contains an array of `coordinates`, with each `coordinate` representing the location of the connection on a specific floor. In the case of an elevator, each `coordinate` would have `latitude` and `longitude` values that are the same with different `floorIds`. Stairs may have `coordinates` with the same or different `latitude` and `longitude` values on each floor, depending on whether a building's stairs are vertically aligned.

The following code snippet retrieves all connections from the map.


```ts
const connections = mapData.getByType("connection");
```

### Dynamic Focus

# Dynamic Focus

> 

> 

A single venue may include multiple nearby buildings, each contained within a FloorStack. Dynamic Focus enables seamless exploration across these buildings by revealing indoor content as the camera pans over each structure. There are two ways to implement Dynamic Focus.

**1. Dynamic Focus Package**

The first approach is to use the Mappedin Dynamic Focus package @mappedin/dynamic-focus, which is a standalone package that can be used in conjunction with Mappedin JS. It provides a simple API for implementing Dynamic Focus, allowing automatic switching between building facades and building maps as they move into and out of focus when the map is panned. The Dynamic Focus package will trigger the same `facades-in-view-change` and `floor-change` events as the Implementing Dynamic Focus using MapView method, allowing the app to listen for these events and update the map view accordingly, such as showing and hiding markers or labels when focus is transitioned to a new building.

**2. Dynamic Focus using MapView.updateState**

The second approach is to use the MapViewControl.updateState method to update the map view when the camera pans over a building. This approach is more flexible and allows for more control over Dynamic Focus behavior, but it requires more code to implement. This can allow for custom behaviour, such as showing the the building map of different elevations. This can be useful when floors of nearby buildings don't share the same elevation, such as when level 2 of one building is aligned with level 3 of another building. It could also allow for showing and hiding markers or labels when focus is transitioned to a new building.

!Mappedin Dynamic Focus

_Mappedin Dynamic Focus with Auto Focus Enabled_

## Implementing the Mappedin Dynamic Focus Package

The Mappedin Dynamic Focus package offers a simple API for implementing Dynamic Focus. If custom behaviour is required refer to the Implementing Dynamic Focus using MapView section.

### Installation

Dynamic focus is provided as a separate package that works in conjunction with Mappedin JS. To install the @mappedin/dynamic-focus package from npm, run the following command:

With NPM:


```bash
npm install @mappedin/dynamic-focus
```


With Yarn:


```bash
yarn add @mappedin/dynamic-focus
```


### Usage

The Dynamic Focus controller is instantiated using the `useDynamicFocus` hook in the `@mappedin/dynamic-focus/rn` package. It must be done so within the context of a `MapView` component. The following example demonstrates how to create a new Dynamic Focus controller and enables auto focus to automatically transition the currently visible map from one building to the next as the camera pans over it.


```tsx
import React, { useEffect } from 'react';
import { MapView, useMapData } from '@mappedin/react-sdk';
import { useDynamicFocus } from '@mappedin/dynamic-focus/rn';

function MyComponent() {
	const { mapData } = useMapData({
		key: 'your-api-key',
		secret: 'your-api-secret',
		mapId: 'your-map-id',
	});

	return (
		<MapView mapData={mapData}>
			<DynamicFocusDisplay />
		</MapView>
	);
}

function DynamicFocusDisplay() {
	// No need to pass mapView - automatically fetched from context
	const dynamicFocus = useDynamicFocus();

	useEffect(() => {
		if (!dynamicFocus.isEnabled) {
			dynamicFocus.enable();
		}
	}, [dynamicFocus.enable, dynamicFocus.isEnabled]);

	return (
		<div>
			<p>Is Indoor: {dynamicFocus.isIndoor ? 'Yes' : 'No'}</p>
			<p>Is Outdoor: {dynamicFocus.isOutdoor ? 'Yes' : 'No'}</p>
		</div>
	);
}
```


Dynamic Focus has a number of options that can be enabled either at instantiation or at any time via `updateState()`.


```ts
dynamicFocus.updateState({
    autoFocus: true, // whether to automatically focus on camera move
    indoorZoomThreshold: 18, // the zoom level at which the indoors is revealed
    outdoorZoomThreshold: 17, // the zoom level at which the indoors are hidden
    setFloorOnFocus: true, // whether to automatically call setFloor during focus
    indoorAnimationOptions: {
        // options for the animation to fade out the facades
        duration: 150,
    },
    outdoorAnimationOptions: {
        // options for the animation to fade in the facades
        duration: 150,
    },
});
```


### Auto Focus

Dynamic Focus' auto focus provides default behavior to transition the currently visible map from one building to the next as the camera pans over it. The default behavior can be overridden by setting the `autoFocus` option to `false`, allowing the developer to control the focus manually.


```ts

/**
 * Create a new Dynamic Focus controller that automatically updates the MapView.
 */
const dynamicFocus = useDynamicFocus();

/**
 * Enable Dynamic Focus.
 */
dynamicFocus.enable({
  autoFocus: true,
  setFloorOnFocus: true,
});

/**
 * Disable automatic updates - now the app needs to manually call `focus()` to update the view.
 */
dynamicFocus.updateState({ autoFocus: false });

/**
 * Manually trigger a focus update to show/hide facades and update floor visibility.
 * This shows the default Floor in the FloorStack that is currently centered on the map.
 */
dynamicFocus.focus();

/**
 * Clean up the controller and restore default floor visibility behavior
 */
dynamicFocus.destroy();
```


### Setting FloorStack Default Floor

The default floor is the Floor that is visible when focus is transitioned to a new FloorStack (building). The default Floor for a FloorStack can be set by calling `setDefaultFloorForStack()` with the floor stack and floor ID. The default floor can be reset by calling `resetDefaultFloorForStack()` with the floor stack.


```ts
const dynamicFocus = useDynamicFocus();
dynamicFocus.setDefaultFloorForStack(floorStack, floor);
dynamicFocus.resetDefaultFloorForStack(floorStack);
```


## Implementing Dynamic Focus using MapView

Dynamic Focus can be implemented using the MapViewControl.updateState method. This approach is more flexible and allows for full customization of Dynamic Focus behavior, but it requires more code to implement. For a simple implementation of Dynamic Focus, refer to the Mappedin Dynamic Focus Package section.

Implementing Dynamic Focus using MapViewControl.updateState requires the app to switch the visibility of a building Facade and Floor when the camera pans over a building. The Facade represents the look of the building from the outside, with its roof on. The Floor represents the look of the building from the inside, showing the indoor map.

### Listen for Changes to Facades In view

The `facades-in-view-change` event is emitted when the facades in view change. This event is emitted when the camera pans over a building. The event provides the list of facades in view. The app can use this event to update the visibility of the facades and floors. The first Facade in the array contains the one that is most centered in view.


```tsx
// Act on the facades-in-view-change event to update floor visibility.
const [facadesInView, setFacadesInView] = useState<Set<string>>(new Set());
useMapViewEvent("facades-in-view-change", (event) => {
  const { facades } = event;

  const newFacadesInView = new Set<string>();

  if (facades.length > 0) {
    for (const facade of facades) {
      newFacadesInView.add(facade.id);
    }
    const primaryFacade = facades[0];
    const primaryFloor =
      floorToShowByBuilding.get(primaryFacade.floorStack.id) ??
      primaryFacade.floorStack.defaultFloor;
    mapView.setFloor(primaryFloor);
  }

  setFacadesInView(newFacadesInView);
});
```


### Listen for Changes to the Floor

The `floor-change` event is emitted when the floor changes, for example when the user selects a new floor from a floor selector or when they click on a navigation marker to go up or down stairs or an elevator. The event provides the new floor. The app can use this event to update the visibility of the facades and floors.


```tsx
// Act on the floor-change event to update the level selector.
useMapViewEvent("floor-change", (event) => {
  const { floor: newFloor } = event;
  elevation = newFloor.elevation;
  console.log("Elevation: " + elevation);
  updateFloorsToShow();

  mapData.getByType("floor-stack").forEach((fs) => {
    if (fs.facade) {
      if (
        facadesInView.has(fs.facade.id) ||
        fs.id === newFloor.floorStack.id
      ) {
        openFacade(fs.facade);
      } else {
        closeFacade(fs.facade);
      }
    }
  });

  console.log(
    "Floor changed to:",
    event?.floor.name,
    "in building:",
    event?.floor.floorStack.name
  );
});

// Open the building's facade and show its indoor map.
function openFacade(facade: Facade) {
  if (animationsByFacade.has(facade.id)) {
    animationsByFacade.get(facade.id)?.cancel();
  }
  // first, show the floor we want to see
  showFloors(facade.floorStack);
  if (mapView.getState(facade)!.opacity === 0) {
    // already animated out
    return;
  }
  // then, animate the facade out
  const animation = mapView.animateState(
    facade,
    {
      opacity: 0,
    },
    {
      duration: animationDuration,
    }
  );
  animationsByFacade.set(facade.id, animation);
  animation.then(() => {
    animationsByFacade.delete(facade.id);
  });
}

// Close the building's facade and hide its indoor map.
function closeFacade(facade: Facade) {
  if (animationsByFacade.has(facade.id)) {
    animationsByFacade.get(facade.id)?.cancel();
  }
  if (mapView.getState(facade)!.opacity === 1) {
    // already animated in
    return;
  }

  // first, animate the facade in
  const animation = mapView.animateState(
    facade,
    {
      opacity: 1,
    },
    {
      duration: animationDuration,
    }
  );
  animationsByFacade.set(facade.id, animation);
  animation.then(() => {
    animationsByFacade.delete(facade.id);
    // then, hide the other floors
    facade.floorStack.floors.forEach((floor) => {
      mapView.updateState(floor, {
        visible: false,
      });
    });
  });
}
```

### Enterprise Data

# Enterprise Data

> 

> 

> The Enterprise Data classes described in this guide are populated in Mappedin CMS, which requires an Enterprise Tier subscription.

## Enterprise Locations

A Mappedin.EnterpriseLocation contains metadata about a location, such as its name, description, logo, phone number, social medial links, hours of operation and more. They can be accessed using the Mappedin.MapData.getByType() method as shown below.


```ts
const allLocations = mapData.getByType('enterprise-location');
```


Here is an example of the data contained within Mappedin.EnterpriseLocation.

!enterprise-location-example-data

## Enterprise Categories

A Mappedin.EnterpriseCategory groups one or more Mappedin.EnterpriseLocation. These allow similar locations to be sorted in a logical fashion. For example a mall may group locations into Food Court, Footwear and Women's Fashion. They can be accessed using the Mappedin.MapData.getByType() method as shown below.


```ts
mapData.getByType('enterprise-category');
```


Here is an example of the data contained within Mappedin.EnterpriseCategory.

!enterprise-category-example-data

Mappedin.EnterpriseCategory can contain one or more sub Mappedin.EnterpriseCategory that are accessed from its children accessor. Mappedin.EnterpriseCategory also contains a name, array of Mappedin.EnterpriseLocation and other metadata.

## Enterprise Venue

The Mappedin.EnterpriseVenue class holds metadata about the map, which includes the map name, supported languages, default language, top locations and more. It can be accessed using the Mappedin.MapData.getByType() method as shown below.


```ts
mapData.getByType('enterprise-venue');
```


Here is an example of the data contained within Mappedin.EnterpriseVenue.

!enterprise-venue-example-data

## Enterprise Search

The Mappedin.Search functionality allows users to search for locations, categories, and other points of interest within the venue. Here are two ways to enable search:

1. Enable Search on map initialization (Recommended):


```tsx
<MapView
  mapData={{
    key: KEY,
    secret: SECRET,
    mapId: MAP_ID,
    search: {
        enabled: true,
    },
  }}
  options={{}}
>
</MapView>
```


2.  Enable Search via method:


```ts
await mapData.Search.enable();
```


### Search Query

Use Mappedin.Search.query to search for locations based on a string input:

-   Mappedin.EnterpriseLocation: Specific places such as stores, restaurants, or washrooms.
-   Mappedin.EnterpriseCategory: Groups of locations, such as "Food Court" or "Electronics."
-   Mappedin.Places: Any main objects that can be searched for such as Mappedin.Space, Mappedin.Door, Mappedin.PointOfInterest

Search query returns a list of matching Mappedin.SearchResults based on the input string.

Mappedin.SearchResults include information about the type of match, the score (relevance), and detailed metadata about the matching items.

#### Example Search Query


```ts
const results = await mapData.Search.query('Coffee Shop');

// Log the entire result object
console.log(results);
```


#### Example Response


```ts
{
    "places": [
        {
            "type": "space",
            "match": {
                "coffee": ["description"],
                "shop": ["description"],
                "shopping": ["description"]
            },
            "score": 19.5,
            "item": {
                "id": "s_ef330e70329183b4",
                "name": "Take Five Cafe",
                "type": "room",
                "floor": "f_8ca999c2cbcb6022",
                "center": {
                    "latitude": 43.860466138841865,
                    "longitude": -78.94643735347043,
                    "floor": "f_8ca999c2cbcb6022"
                }
            }
        }
    ],
    "enterpriseLocations": [
        {
            "type": "enterprise-location",
            "match": {
                "coffee": ["tags", "description"]
            },
            "score": 24.3,
            "item": {
                "id": "el_094c671a5bc73fb7",
                "name": "Nespresso"
            }
        }
    ],
    "enterpriseCategories": [
        {
            "type": "enterprise-category",
            "match": {
                "shop": ["locations.name"]
            },
            "score": 9.4,
            "item": {
                "id": "ec_5cf9b7898619b951",
                "name": "Health & Beauty"
            }
        }
    ]
}

```


#### Response Field Breakdown

1. Mappedin.Places:

    - `type`: Indicates the type of match (e.g., space).
    - `match`: Shows the fields that matched the query (e.g., description).
    - `score`: Relevance score of the match.
    - `item`: Includes id, name, type, floor, and center (coordinates).

2. Mappedin.EnterpriseLocation:

    - `type`: enterprise-location.
    - `match`: Indicates fields matched (e.g., tags, description).
    - `item`: Contains id, name, and additional metadata.

3. Mappedin.EnterpriseCategory:

    - `type`: enterprise-category.
    - `match`: Indicates query matches to category-related data.
    - `item`: Contains id and name.

### Search Suggestions

Use Mappedin.Search.suggest to fetch real-time suggestions based on partial input. This is useful for creating an autocomplete feature for a search bar.

#### Example Code


```ts
// fetch suggestions for partial input "Coff"
const suggestions = await mapData.Search.suggest('Coff');

// log the suggestions
console.log(suggestions);

// log suggestion names
suggestions.forEach(suggestion => {
    console.log(`Suggestion: ${suggestion.suggestion}`);
});
```


#### Example Response

Here's a sample response for the query 'Coff':


```ts
[
    {
        suggestion: 'coffee',
        terms: ['coffee'],
        score: 7.558366632976704,
    },
];
```


#### Response Field Breakdown

1. `suggestion`: The suggested term or phrase (e.g., "coffee").
2. `terms`: An array of individual terms that make up the suggestion.
3. `score`: A numerical value representing the relevance of the suggestion.

## Events & Deals

Events and deals created in Mappedin CMS can be retrieved using the @mappedin/events package.

### Installation

To use the @mappedin/events package, you need to install it using npm or yarn.

**Using npm**


```bash
npm install @mappedin/events
```


**Using yarn**


```bash
yarn add @mappedin/events
```


### Usage

The following example demonstrates how to load and display events on a map.


```tsx
const { mapData } = useMap();

// Create an EventManager to load and read event data
const em = new EventsManager(mapData);

// Load all events
await em.load();

// Create markers for all events with the event name at the location of the event
return (
  <>
    {em.events.map(event => (
      <Marker
        key={event.id}
        target={event.location?.spaces[0]}
        text={event.name}
      />
    ))}
  </>
);
```


### Options

The `EventsManager` constructor accepts an optional `options` parameter. The following options are available:


```ts
/**
 * Options for the {@link EventsManager}.
 */
export type EventsManagerOptions = Partial<{
	/**
	 * The fields to fetch for each event.
	 *
	 * @default fields id, name, type, startDate, endDate, externalId, description, location, image, video
	 */
	fields: string[];
	/**
	 * Whether to include past or expired events.
	 *
	 * @default false
	 */
	includeExpired: boolean;
}>;
```


### Methods

The `EventsManager` class provides the following methods:


```ts
class EventsManager {
	/**
	 * Whether load() has been called and successfully completed.
	 */
	get ready(): boolean;

	/**
	 * All current and future events that have been loaded. Will be empty if load() has not been called.
	 */
	get events(): EventMetaData[];

	/**
	 * Load all the events for the map.
	 */
	async load(): void;

	/**
	 * Get an event by ID.
	 */
	getById(id: string): EventMetaData | undefined;

	/**
	 * Get an array of events attached to an EnterpriseLocation.
	 */
	getByLocationId(locationId: string): EventMetaData[];

	/**
	 * Clean up the EventsManager instance.
	 */
	destroy(): void;
}
```

### Getting Started

# Getting Started

> 

> 

Mappedin SDK for React Native enables integration of Mappedin's indoor mapping and navigation capabilities into React Native applications. This SDK provides a native wrapper around Mappedin's web-based mapping technology using a WebView for cross-platform compatibility. Mappedin SDK for React Native uses the `react-native-webview` package to display the map.

This getting started guide demonstrates how to start a project using Mappedin SDK for React Native. Following this guide results in a working demo with a map that you can interact with (zoom, pan, rotate etc).

## Requirements

Mappedin SDK for React Native v6 supports the following:

-   React 16.8.0+
-   React Native 0.60.0+
-   React Native WebView 11.0.0+
-   Expo 39+

When using `@mappedin/react-native-sdk`, also install and import `@mappedin/mappedin-js`. Use the same version of Mappedin JS `@mappedin/react-js`as the Mappedin SDK for React Native `@mappedin/react-native-sdk"`. They are released with matching versions to ensure compatibility.

> Mappedin SDK for React Native v6 is available as @mappedin/react-native-sdk@beta in NPM.

> You can find the Mappedin React Native demo application on Github at https://github.com/mappedin/react-native

## Coding with AI

Mappedin SDK for React Native provides an llms-mappedin-react-native.txt file that can be used to help with coding when using Large Language Models (LLMs).



## MapView

The MapView component contains the DOM element of the 3D map and the context wrapper for control of the map. Components which reference the 3D map must be children of the `MapView` component to have access to the context.


```tsx
import React from "react";
import { View, StyleSheet } from "react-native";
import { MapView } from "@mappedin/react-native-sdk";

// See Demo API key Terms and Conditions
// Demo Key & Maps: https://developer.mappedin.com/docs/demo-keys-and-maps
const App = () => {
  return (
    <View style={styles.container}>
      <MapView
        mapData={{
          key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
          secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
          mapId: "660c0c3aae0596d87766f2da",
        }}
        options={{}}
      >
      </MapView>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#f0f8ff",
  },
});

export default App;
```


## useMap

The useMap hook returns an object containing an instance of MapViewControl and MapData. This hook can be used after the map has been loaded and rendered. `useMap` must be used in a child component of MapView. Use the MapViewControl instance to access the map's methods and properties.


```tsx
function MyCustomComponent() {
    const { mapView, mapData } = useMap();

    return mapData.getByType('space').map(space => {
        return <Label target={space.center} text={space.name} />;
    });
}
```


## useMapViewEvent

The useMapViewEvent hook enables subscribing to interactive map events and triggering a callback when they occur.

For example, the following snippet subscribes to the `click` event and updates state using the click coordinate. `Label`s are rendered based on the updated state. The `click` event contains all the interactive elements that the click action passed through.

> See full JavaScript guides about Interactivity and the Camera for more information about events.


```tsx
function MyCustomComponent() {
    const { mapView, mapData } = useMap();
    const [labels, setLabels] = useState([]);

    useMapViewEvent('click', event => {
        setLabels(prevLabels => [
            ...prevLabels,
            { target: event.coordinate, text: 'Hello, World!' },
        ]);
    });

    return labels.map((label, idx) => <Label key={idx} {...label} />);
}
```


Other useful events include `hover`, `camera-change`, and `floor-change`. Refer to the useMapViewEvent documentation for a complete list of events.

The `hover` event is very similar to the `click` event and will contain all the interactive elements that are underneath the mouse cursor.


```tsx
useMapViewEvent('hover', event => {
    console.log('hover', event);
});
```


The `camera-change` event fires when the camera is adjusted. It contains the new `bearing`, `pitch`, `zoomLevel` and camera `center` coordinate.


```tsx
useMapViewEvent('camera-change', event => {
    console.log('camera-change', event.bearing, event.pitch, event.zoomLevel, event.center);
});
```


The `floor-change` event fires whenever the building floor is changed. It contains the `floor` and the `reason` that the change occurred.


```tsx
useMapViewEvent('floor-change', event => {
    console.log('floor-change', event.floor, event.reason);
});
```


## Local Development

For local development, start a project using Expo. Refer to the React Native Getting Started guide for setup details. Guides are written in TypeScript (JavaScript), as the SDK is written in Typescript and uses comprehensive types.

When using `@mappedin/react-native-sdk`, also install and import `@mappedin/mappedin-js`. Use the same version of Mappedin JS `@mappedin/react-js`as the Mappedin SDK for React Native `@mappedin/react-native-sdk"`. They are released with matching versions to ensure compatibility.

### 1. Create a Project

> Note that Mappedin SDK for React Native version 6 is currently in an beta state. Therefore you must append @beta when adding the Mappedin package. Failing to do so will add the current production release of version 5, which does not support maps in the Free, Plus, Advanced or Pro tiers.

Run these shell commands to set up a new project and install Mappedin SDK for React Native.

**Create a new Expo project**

The following command will create a new Expo project with a blank Typescript template.


```bash
npx create-expo-app@latest my-mappedin-app --template blank-typescript
```


### 2. Install Mappedin SDK for React Native

Using NPM:

Change to the project directory and install the Mappedin SDK for React Native and its peer dependencies.


```bash
cd my-mappedin-app
npm install @mappedin/react-native-sdk@beta
npm install react react-native react-native-webview
```


Using Yarn:


```bash
cd my-mappedin-app
yarn add @mappedin/react-native-sdk@beta
yarn add react react-native react-native-webview
```


### 3. Update App.tsx

Modify & update the contents of `App.tsx` to match the following.


```tsx title=App.tsx
import React, { useEffect } from "react";
import { View, StyleSheet } from "react-native";
import { MapView, useMap } from "@mappedin/react-native-sdk";

const MapSetup = () => {
  const { mapData, mapView } = useMap();

  useEffect(() => {
    if (mapData && mapView) {
      console.log("Map is ready!");

      async function initializeMap() {
        // Label all spaces.
        mapView.Labels.all();
      }

      initializeMap();
    }
  }, [mapData, mapView]);

  return null;
};

// See Demo API key Terms and Conditions
// Demo Key & Maps: https://developer.mappedin.com/docs/demo-keys-and-maps
const App = () => {
  return (
    <View style={styles.container}>
      <MapView
        mapData={{
          key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
          secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
          mapId: "660c0c3aae0596d87766f2da",
        }}
        options={{}}
      >
        <MapSetup />
      </MapView>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#f0f8ff",
  },
});

export default App;
```


## 4. Run the project

Run the project using the following command. When prompted, press `a` to run the project on Android or `i` to run the project on iOS.

The 3D rendered map can be zoomed, panned and rotated via mouse or fingers.

Using NPM:


```bash
npm run start
```


Using Yarn:


```bash
yarn start
```


An example of a React Native application that showcases many features of Mappedin SDK for React Native can be found in the Mappedin React Native Github Repository.

## Create a Key & Secret



## Authenticating with a Bearer Token

Mappedin SDK for React Native can also be authenticated with a short lived bearer token. This can be used to prevent exposing an API key and secret by generating a token on the server side. The server can securely store the API key and secret, allowing the client to use the token to authenticate with Mappedin SDK for React Native.

To do so, make a request to the API Key REST endpoint sending the API key and secret. The following TypeScript example shows how to do this using a fetch request. Additional examples can found in the API Key REST documentation.


```ts
async function getAccessToken(): Promise<string> {
    // See Trial API key Terms and Conditions
    // https://developer.mappedin.com/docs/demo-keys-and-maps
    const response = await fetch('https://app.mappedin.com/api/v1/api-key/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            key: 'YOUR_KEY',
            secret: 'YOUR_SECRET',
        }),
    });

    const data: TokenResponse = await response.json();
    return data.access_token;
}
```


The API Key REST endpoint will return JSON that contains the bearer token.


```json
{
    "access_token": "…",
    "expires_in": 172800
}
```


The bearer token can then be used to authenticate with Mappedin JS as shown in the following example.


```tsx
<MapView
  options={{}}
  mapData={{
    mapId: "your-map-id",
    accessToken: "your-access-token",
  }}
>
</MapView>
```


## Optimizing User Interface Performance

To optimize performance and avoid unnecessary re-renders, it's important to use React's memoization techniques. Rendering a MapView can be resource-intensive, especially when dealing with complex maps that include many components. Ensure that components only re-render when necessary, and avoid patterns that trigger cascading re-renders in sub-components.

Avoid defining component properties inline—this can lead to new references on every render. Instead, define them as constants, memoized callbacks (useCallback), or memoized values (useMemo) when appropriate.

## Debug Mode

Use Debug Mode to get a closer look at how various map components behave and interact. Here's how to enable it:

### 1. Enable Debug Mode

To activate the debug interface, call the following function in your code:


```ts
mapView.enableDebug();
```


MapViewControl.enableDebug displays a panel on the right side of the map, revealing several tools and controls for direct interaction with the map's elements.

### 2. Navigating the Debug Panel

The debug panel provides access to a variety of controls:

**Geometry Controls**

-   Adjust individual geometry settings, such as color, opacity, visibility. These controls make it easy to see how different elements respond to changes.

**Interactivity**

-   Use toggles to turn interactivity on/off
-   Change colors and hover effects to highlight specific areas

**Scene Controls**

-   Manage the overall scene settings, such as scaling, positioning, and group management. Toggle the visibility of groups or containers within the scene
-   Adjust padding, scale, and watermark positioning
-   Markers & Labels — Add, remove, or edit markers and labels directly through the panel

**Camera Controls**

-   Fine-tune camera settings, including zoom levels, pitch, and center position
-   Set minimum and maximum zoom levels
-   Adjust the focus to a specific area or level

!enable debug

### Images, Textures & Colors

# Images, Textures & Colors

> 

> 

!Images and Textures

Images, textures and colors can enhance the fidelity of an indoor map. They can be used to add custom branding, highlight important features, or provide additional information to users. Images can be placed on any Mappedin.IAnchorable target on the map and given a `verticalOffset` to control the height at which the image is displayed. Textures can be applied to the top or sides of a Mappedin.MapObject, Mappedin.Space, Mappedin.Door or Wall.

## Requirements & Considerations

JPEG and PNG images are supported for both images and textures. It's important to consider the size of all unique image files displayed on a map at one time. Using many unique images may cause instability on mobile devices with limited GPU memory. Mappedin JS will cache and reuse images that have the same URL, resulting in reduced memory usage. The following calculations illustrates how much memory is used for a given image:

**Formula:** `width * height * 4 bytes/pixel = memory used`

**512 x 512 Pixel Image:** `512px * 512px * 4 bytes/pixel = 1MB`

**4096 x 4096 Pixel Image:** `4096px * 4096px * 4 bytes/pixel = 64MB`

## Creating Images for Spaces

When creating images to be used as the floor of a space, it's important that the image dimensions match the space to avoid it leaking into adjacent spaces. An SVG export of the map can be useful to determine the correct dimensions. The following steps demonstrate how to create an image that matches a space's dimensions using Figma. Similar steps could be used in other image editing tools that support the SVG format.

1. Log into app.mappedin.com and select the map you want to create an image for.
2. Click on the **Download** button and choose `Download as SVG`.
3. Import the SVG into Figma (**File** > **Place Image**).
4. Select the geometry to create the image for by clicking near the center of it (not the edge).
5. Choose **File** > **Place** Image to place the image you want to use as the floor.
6. Click the geometry to fill.
7. Click **Export** (bottom right).
8. Choose format (PNG or JPEG), size and export.

The exported image should match the dimensions of the space.

## Images

The Mappedin.Image3D class is accessed through MapViewControl.Image3D and used to add and remove images to and from the map. Images can be placed on any Mappedin.IAnchorable target. TAddImageOptions is used to configure the image and specifies its width, height, rotation, vertical offset and whether the image is rotated to face the camera. The following example places an image on a Space named "Arena".


```ts
const IMAGE_URL = 'https://x6ccjn.csb.app/arena-floor.png';
const arenaFloor = mapData.getByType('space').find((space) => space.name === 'Arena');

// Configure the images size and rotation.
// Using an offset of 0.1 to place it just above the map's floor.
// Use pixelsToMeters to convert pixels to meters. This value will vary based on the map size.
const pixelsToMeters = 0.0617;
const controller: Mappedin.TAddImageOptions = {
	width: 1014 * pixelsToMeters,
	height: 448 * pixelsToMeters,
	rotation: 121,
	verticalOffset: 1,
	flipImageToFaceCamera: false,
};

// Add the default image to the arena floor.
mapView.Image3D.add(arenaFloor, IMAGE_URL, controller);
```


## Textures & Colors

Walls, doors, floors and objects can be given textures or colors, which can be applied individually to the top or sides. The Mappedin.TGeometryState type is used to configure the texture and color, which is applied by calling MapViewControl.updateState.

When applying textures to walls it is important to set Mappedin.TShow3DMapOptions.shadingAndOutlines to false in the MapView's MapViewProps.options. This will prevent lines from being drawn between the top and side textures.

Be sure to review the Requirements & Considerations section before applying textures.

### Doors

The top and sides of a door can be given textures or colors. The example below demonstrates how to set the color of all interior and exterior doors. Doors can also be made visible on an individual basis by passing in a Mappedin.Door object to MapViewControl.updateState().


```ts
//Make interior doors visible, sides brown and top yellow.
mapView.updateState(Mappedin.DOORS.Interior, {
	visible: true,
	color: 'brown',
	topColor: 'yellow',
	opacity: 0.6,
});

//Make exterior doors visible, sides black and top blue.
mapView.updateState(Mappedin.DOORS.Exterior, {
	visible: true,
	color: 'black',
	topColor: 'blue',
	opacity: 0.6,
});
```


### Objects

Objects can be given textures or colors, which can be applied individually to the top and sides. The following example demonstrates how to set the texture of the side and color of the top of all objects.


```ts
mapData.getByType('object').forEach((object: Mappedin.MapObject) => {
	mapView.updateState(object, {
		texture: {
			url: 'https://example.com/object-side-texture.png',
		},
		topColor: '#9DB2BF',
	});
});
```


### Spaces

The floor of a space can be given a texture or color. When creating an image for the floor of a space, it's important that the image dimensions match the space to avoid it leaking into adjacent spaces. Refer to the Creating Images for Spaces section for more information. The following example demonstrates how to set the texture of the floor for all spaces.


```ts
mapData.getByType('space').forEach((space: Mappedin.Space) => {
	mapView.updateState(space, {
		topTexture: {
			url: FLOOR,
		},
	});
});
```


### Walls

The exterior and interior walls of a building can be targeted with different textures and colors. The following example demonstrates how to set the texture of an exterior wall and the colors of interior walls. Note that both types of walls support textures and colors.


```ts
// Disable shadingAndOutlines to prevent lines from appearing between the top and side textures.
const mapView = await show3dMap(document.getElementById('mappedin-map') as HTMLDivElement, mapData, {
	shadingAndOutlines: false,
});

mapView.updateState(Mappedin.WALLS.Exterior, {
	texture: {
		url: 'https://example.com/wall-side-texture.png',
	},
	topTexture: {
		url: 'https://example.com/wall-top-texture.png',
	},
});

mapView.updateState(Mappedin.WALLS.Interior, {
	color: '#526D82',
	topColor: '#27374D',
});
```

### Interactivity

# Interactivity

> 

> 

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

> A complete example demonstrating interactivity can be found in the Mappedin React Native Github repo: interactivity.tsx

!Mappedin JS v6 Interactivity

## Interactive Spaces

Spaces can be set to interactive to allow a user to click on them. When interactivity is enabled for a space, it enables a hover effect that highlights the space when the cursor is moved over the space.

The following code enables interactivity for all spaces:


```ts
// Set each space to be interactive.
mapData.getByType('space').forEach((space: Mappedin.Space) => {
	mapView.updateState(space, {
		interactive: true,
	});
});
```


## Hover Interactivity

When interactivity is enabled for a space, it enables a hover effect that highlights the space when the cursor is moved over the space. The highlight color can also be customised to match the style of the map.

The following code sample enables interactivity for all spaces on the map and sets the hover color to red.


```ts
// Set each space to be interactive and its hover color to red.
mapData.getByType('space').forEach((space: Mappedin.Space) => {
	mapView.updateState(space, {
		interactive: true,
		hoverColor: 'red',
	});
});
```


## Interactive Labels

Labels added to the map can be set to interactive to allow users to click on them and have the click event captured by an app. The code sample below adds a label to each space with a name and sets the label's interactivity to true.


	
    
```tsx
    // 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,
          }}
          onLoad={(label) => {
            console.log("Label loaded:", label);
          }}
        />
      ))}
    </>
    );
    ```
`

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

  


After enabling interactivity, click events on the label can be captured using the useMapViewEvent hook. The Mappedin.TClickPayload object passed into the hook will contain an array of labels that were clicked.

The following code sample captures the click event and checks if the user clicked on a label. If they did, it logs the id of the label that was clicked and focuses the camera on the label.


```tsx
// Act on the click event to log the id of the label and
// focus the camera on the label.
  useMapViewEvent("click", (payload: Mappedin.TClickPayload) => {
      if (payload.labels && payload.labels.length > 0) {
        const label = payload.labels[0];
        console.log("Clicked on label: " + label.id);

        mapView.Camera.focusOn(label, {
          maxZoomLevel: 20,
          duration: 300,
          easing: "ease-in-out",
        });
      }
  });
```


## Interactive Markers

Markers are another component that can be set to interactive, allowing them to be clickable and have an app act on the click event. The `interactive` property of a Marker can be set to `true`, `false` or `pointer-events-auto`.

-   `false` - The Marker is not interactive.
-   `true` - The Marker is interactive and the click event is captured by the 'MapView' event handler.
-   `pointer-events-auto` - The Marker is interactive and mouse events are passed to the Marker's HTML content.

The code sample below adds a marker to each space with a name and sets the marker's interactivity to true.


```tsx
// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);

// Add a Marker on all spaces with its space name and make them interactive.
return (
<>
  {spaces.map(space => (
    <Marker
      key={space.externalId}
      target={space}
      html={`
        <div>
          ${space.name}
        </div>
      `}
      options={{
        interactive: true,
      }}
      onLoad={(marker: Mappedin.Marker) => {
        console.log("Marker marker loaded:" + marker.id);
      }}
    />
  ))}
</>
);
```


After enabling interactivity, click events on the marker can be captured using the useMapViewEvent hook. The Mappedin.TClickPayload object passed into the hook will contain an array of markers that were clicked.

The following code sample captures the click event and checks if the user clicked on a marker. If they did, it logs the id of the marker that was clicked and focuses the camera on the marker.


```tsx
// Act on the click event to log the id of the marker and
// focus the camera on the marker.
  useMapViewEvent("click", (payload: Mappedin.TClickPayload) => {
      if (payload.markers && payload.markers.length > 0) {
        const marker = payload.markers[0];
        console.log("Clicked on marker: " + marker.id);

        mapView.Camera.focusOn(marker, {
          maxZoomLevel: 20,
          duration: 300,
          easing: "ease-in-out",
        });
      }
  });
```


## Handling Click and Hover Events

Mappedin SDK for React Native enables capturing and responding to click and hover events through its event handling system. After enabling interactivity, click or hover events on the space can be captured using useMapViewEvent hook.

The Mappedin.TEvents `click` and `hover` events pass Mappedin.TClickPayload that contains the objects the user clicked or hovered on. It allows developers to obtain information about user interactions with various elements on the map, such as:

1. **blueDot**: A boolean value indicating if the user clicked on the blue dot.
2. **coordinate** - A Mappedin.Coordinate object that contains the latitude and longitude of the point where the user clicked.
3. **facades** - An array of Mappedin.Facade objects that were clicked.
4. **floors** - An array of Mappedin.Floor objects. If the map contains multiple floors, floors under the click point are included.
5. **labels** - An array of Mappedin.Label objects that were clicked.
6. **markers** - An array of Mappedin.Marker objects that were clicked.
7. **models** - An array of Mappedin.Model objects that were clicked.
8. **objects** - An array of Mappedin.MapObject objects that were clicked.
9. **paths** - An array of Mappedin.Path objects that were clicked.
10. **pointerEvent** - A Mappedin.PointerEvent object that contains the pointer event data.
11. **shapes** - An array of Mappedin.Shape objects that were clicked.
12. **spaces** - An array of Mappedin.Space objects that were clicked.

Use `useMapViewEvent("click"...` or `useMapViewEvent("hover"...` to capture click or hover events as shown below.


```tsx
useMapViewEvent("click", (payload: Mappedin.TClickPayload) => {
  // The user clicked!
});

useMapViewEvent("hover", (payload: Mappedin.THoverPayload) => {
  // The user hovered!
});
```


> A complete example demonstrating interactivity can be found in the Mappedin React Native Github repo: interactivity.tsx

### Labels

# Labels

> 

> 

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.

!Mappedin JS v6 Labels

> 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.

> A complete example demonstrating labels can be found in the Mappedin React Native Github repo: labels.tsx

## 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:


  
    
```tsx
    // 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}
          />
        ))}
      </>
    );
    ```


  
  
    
```ts
    // 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.


```ts
// 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:


  
    
```tsx
    // 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
          />
        ))}
      </>
    );
    ```


  
  
    
```ts
    // 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:


```ts
// 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)                                               |
| ----------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------- |
| !Floating Label fill | !Floating Label contain | !Floating Label cover |

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`                                                                          |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| !Floating Label fill with 0 padding | !Floating Label fill with 10 padding |

Label icons can be configured to be shown or hidden based on the current zoom level using Mappedin.TLabelAppearance.iconVisibleAtZoomLevel. This defines the zoom level at which the icon becomes visible. Infinity ensures never visible, -Infinity ensures always visible.

## 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.

  | Option | Type | Description | Default |
  |--------|------|-------------|---------|
  | `margin` | `number` | Margin around the label text and pin in pixels. This will affect label density. Minimum is 6px. | 6 |
  | `maxLines` | `number` | Number of lines to display when text spans multiple lines. | 2 |
  | `textSize` | `number` | Text size in pixels | 11.5 |
  | `maxWidth` | `number` | Maximum width of text in pixels. | 150 |
  | `lineHeight` | `number` | Line height sets the height of a line box. It's commonly used to set the distance between lines of text. | 1.2 |
  | `color` | ColorString | A ColorString for the label text and pin. | `#333` |
  | `outlineColor` | ColorString | A ColorString for the outline around the label text and pin. | `white` |
  | `textColor` | ColorString | A ColorString representing just the text color. Defaults to the same as `color`. | - |
  | `textOutlineColor` | ColorString | A ColorString representing just the text outline. Defaults to the same as `outlineColor`. | - |
  | `pinColor` | ColorString | A ColorString representing just the pin color. Defaults to the same as `color`. | - |
  | `pinOutlineColor` | ColorString | A ColorString representing just the pin outline. Defaults to the same as `outlineColor`. | - |
  | `pinColorInactive` | ColorString | A ColorString representing just the pin color when the label is inactive. Defaults to the same as `pinColor`. | - |
  | `pinOutlineColorInactive` | ColorString | A ColorString representing just the pin outline when the label is inactive. Defaults to the same as `pinOutlineColor`. | - |
  | `icon` | `string` | An icon to be placed inside the label pin. Can be an SVG string or a path to a PNG or JPEG. | - |
  | `iconSize` | `number` | Size of the icon in pixels. Requires `icon` to be set. | 20 |
  | `iconScale` | `number` \| Interpolation | Scale the icon uniformly. Specify a number or an Interpolation object. | 1 |
  | `iconPadding` | `number` | Padding between the icon and the marker's border in pixels. | 2 |
  | `iconFit` | `'fill'` \| `'contain'` \| `'cover'` | How the icon should fit inside the marker. Options: `fill` (stretch to fill), `cover` (maintain aspect ratio and fill), `contain` (maintain aspect ratio and fit inside). | `cover` |
  | `iconOverflow` | `'visible'` \| `'hidden'` | Whether the icon should overflow the circle of the marker. Options: `visible`, `hidden`. | `hidden` |
  | `iconVisibleAtZoomLevel` | `number` | Defines the zoom level at which the icon becomes visible. Infinity ensures never visible, -Infinity ensures always visible. | -Infinity |

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.


```tsx
// 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>`;

  // Define colors for labels
const colors = ['blue', 'pink', 'green', 'orange', 'tomato', 'gray'];

// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);

return (
    <>
        {spaces.map((space, index) => {
            const color = colors[index % colors.length]; // Cycle through colors
            const icon = `<svg width="24" height="24" xmlns="http://www.w3.org/2000/svg"><circle cx="12" cy="12" r="10" fill="${color}" /></svg>`;

            return (
                <Label
                    key={space.externalId}
                    target={space}
                    text={space.name} // Label text
                    options={{
                        appearance: {
                          color: color,
                          icon: icon, // Custom SVG icon
                        },
                        interactive: true, // Make the label interactive
                    }}
                />
            );
        })}
    </>
);
```


Showing a map with labels with custom styling and icons.

!Labels with custom styling

## 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.


    
    
```tsx
    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
    useMapViewEvent('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
                    }}
                />
            ))}
        </>
    );
    ```


    
    
    
```ts
    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:


  
    
```tsx
    const [isEnabled, setIsEnabled] = useState(false);

    return (
      <Label
        target={space}
        text="Dynamic Label"
        options={{
          enabled: isEnabled // label will be hidden when false
        }}
      />
    );
    ```


  
  
    
```ts
    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:


 
    
```tsx
    const [secondaryLabels, setSecondaryLabels] = useState(
      spaces.slice(5).map(space => ({
        target: space,
        text: space.name,
        enabled: false
      }))
    );

    useMapViewEvent('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 }}
          />
        ))}
      </>
    );
    ```


  
  
    
```ts
    // 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 });
          }
        });
      }
    });
    ```


  



> A complete example demonstrating labels can be found in the Mappedin React Native Github repo: labels.tsx

### Location Profiles & Categories

# Location Profiles & Categories

> 

> 

A Location refers to something that represents a physical position on the map, such as an annotation, area, connection (e.g. stairs or elevator), door, point of interest or space. Locations may have a Mappedin.LocationProfile attached to them. The profiles contain information about the location such as its name, description, social media links, opening hours, logo and more. A LocationProfile can have zero to many Mappedin.LocationCategory attached to it. A LocationCategory may have a child or parent category. For example, the parent `Food & Drink` LocationCategory has children such as `Bar`, `Cafe`, `Food Court` and `Mediterranean Cuisine`.

> A complete example demonstrating location profiles and categories  can be found in the Mappedin React Native Github repo: location-profiles-categories.tsx

## LocationProfile

A LocationProfile can be accessed by using the `locationProfiles` property of a location. For example, use Mappedin.Space.locationProfiles to access every LocationProfile of a space. Every LocationProfile can also be access using the Mappedin.MapData.getByType() method as shown below.


```ts
const locationProfiles = mapData.getByType('location-profile');
```


## LocationCategory

To access the Mappedin.LocationCategory of a LocationProfile, use the Mappedin.LocationProfile.categories property. Note that a LocationCategory can have either parent or child categories. These are accessible using the Mappedin.LocationCategory.parent and Mappedin.LocationCategory.children properties respectively. Every LocationCategory can also be access using the MapData.getByType() method as shown below.


```ts
const locationCategories = mapData.getByType('location-category');
```

### Markers

# Markers

> 

> 

Mappedin SDK for React Native allows adding and removing Mappedin.Marker on a map. Markers are elements containing HTML that Mappedin anchors to any IAnchorable target. They are automatically rotated and repositioned when the camera moves.

!Mappedin JS v6 Markers

> Note that the MapViewControl class implements the Mappedin.Markers interface and exposes it as MapViewControl.Markers . Use MapViewControl.Markers to utilize Markers' methods. An instance of MapViewControl is available from the useMap hook.

## Creating Markers

> A complete example demonstrating markers can be found in the Mappedin React Native Github repo: markers.tsx

Markers are added to the map by referencing a target that can be any IAnchorable. The following code sample adds a marker to a coordinate.


  
    
```tsx
    // Get all spaces with names
    const spaces = mapData.getByType('space').filter(space => space.name);

    // Create markers for all spaces with its space name and make them interactive
    return (
      <>
        {spaces.map(space => (
          <Marker
            key={space.externalId}
            target={space}
            text={space.name} // marker text
            options={{ interactive: true }}
          />
        ))}
      </>
    );
    ```


  
	
	
```ts
	mapView.Markers.add(coordinate, '<div>This is a Marker!</div>');
	```

	



The following image shows a map with markers with images.

!Using images on markers

## Placement

Marker placement is set using the `options` argument of Markers.add(). Options accepts a TAddMarkerOptions value, which has a member named `placement`. When provided, the point of the Marker described by the `placement` is placed next to the target. For example, using `center` will place the Marker's center at the target. Both a single placement and an array of placements can be provided. When an array is provided, the Marker is placed at the first target that has space available to display the Marker. Placement positions are defined in TMarkerPlacement which contains 9 values. The placement points are as follows, with the default being center.

### TMarkerPlacement

-   `center`
-   `top`
-   `left`
-   `bottom`
-   `right`
-   `top-left`
-   `top-right`
-   `bottom-left`
-   `bottom-right`

Marker content can be styled using CSS that references the placement of the marker. This can allow the creation of a tooltip or bubble-style marker that points to its target. This is done by using the CSS Selector:


```css
.mappedin-marker[data-placement='<PLACEMENT>'];
```


Where `` is the placement position. Here is an example of adding a triangle pointer to the Marker's target of `left`:


```CSS
.marker:before {
	content: '';
	width: 0;
	height: 0;
	top: calc(50% - 10px);
	left: -10px;
	z-index: 1;
	position: absolute;
	border-bottom: 10px solid transparent;
	border-top: 10px solid transparent;
	z-index: -1;
}

.mappedin-marker[data-placement="left"] .marker:before {
	left: auto;
	right: -5px;
	border-left: 10px solid #333333;
}
```


## Removing Markers

Markers can be removed individually by using the Mappedin.Markers.remove(marker) method, passing in the marker to be removed as shown below.


```ts
mapView.Markers.remove(marker);
```


To remove all markers from a map, call Mappedin.Markers.removeAll().


```ts
mapView.Markers.removeAll();
```


## Marker Rank

Ranking can be added to markers to control which marker will be shown when more than one marker occupies the same space. The marker with the highest rank will be shown. If markers do not overlap, ranking will have no effect. Rank values `low`, `medium`, `high` and `always-visible` as defined in Mappedin.TCollisionRankingTier.

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


  
    
```tsx
    const [markers, setMarkers] = useState<{
      coordinate: Mappedin.Coordinate;
      text: string;
      rank: Mappedin.TCollisionRankingTier;
    }[]>([]);

    // define available ranks and current rank state
    const RANKS: Mappedin.TCollisionRankingTier[] = ['medium', 'high', 'always-visible'];
    const [currentRank, setCurrentRank] = useState(0);

    // handle map clicks to add a marker with a cycling rank
    useMapViewEvent('click', (event) => {
      if (!mapView) return;

      // cycle through rank values
      const newRank = (currentRank + 1) % RANKS.length;
      setCurrentRank(newRank);

      // create a new marker with the current rank
      const newMarker = {
        coordinate: event.coordinate,
        text: `Marker Rank ${RANKS[newRank]}`,
        rank: RANKS[newRank],
      };

      // add new marker to state
      setMarkers((prevMarkers) => [...prevMarkers, newMarker]);
    });

    // render markers using the Marker component
    return (
      <>
        {markers.map((marker, index) => (
          // note: <Marker> component generates a .mappedin-marker class
          <Marker
            key={index}
            target={marker.coordinate}
            options={{
              interactive: true,
              rank: marker.rank
            }}
          >
            <div style={{
              borderRadius: '10px',
              backgroundColor: '#fff',
              padding: '5px',
              boxShadow: '0px 0px 1px rgba(0, 0, 0, 0.25)',
              fontFamily: 'sans-serif',
              textAlign: 'center'
            }}>
              <p style={{
                margin: 0,
                fontSize: '14px'
              }}>
                {marker.text}
              </p>
              <p style={{
                margin: 0,
                fontSize: '10px',
                color: '#666'
              }}>
                Rank: {marker.rank}
              </p>
            </div>
          </Marker>
        ))}
      </>
    );
    ```


  
  
    
```ts
    const RANKS = ['medium', 'high', 'always-visible'] as const;
    let rank = 0 as number;

    // Act on the click event and add a marker with a cycling rank. Observe how higher ranking markers are shown when they collide with lower ranking markers.
    mapView.on('click', async (event) => {
      // TCollisionRankingTier contains 3 values. If rank exceeds 2, reset it to 0.

      const markerTemplate = `
      <div>
        <style>
        .marker {
          display: flex;
          align-items: center;
          background-color: #fff;
          max-height: 64px;
          border: 2px solid grey;
          padding: 4px 12px;
          font-weight: bold;
          font-family: sans-serif;
        }

        .marker img {
          max-width: 64px;
          max-height: 32px;
          object-fit: contain;
          margin-right: 12px;
        }
        </style>
        <div class="marker">
          <p>Marker Rank: ${RANKS[rank]}</p>
        </div>
      </div>`;

      // Add a marker with the current rank at the clicked coordinate.
      mapView.Markers.add(event.coordinate, markerTemplate, {
        rank: RANKS[rank],
      });
      rank++;
      if (rank === RANKS.length) {
        rank = 0;
      }
    });
    ```


  



## Moving Markers

Markers can be repositioned after they have been added to a map. There are two ways of doing this. Using an AnimatedMarker or using the Mappedin.Markers class to call `setPosition` or `animateTo`.

-   Mappedin.Markers.setPosition() instantly repositions a Marker
-   Mappedin.Markers.animateTo() animates a Marker to a new position

The Marker's position can be set to any IAnchorable target.

The `animateTo` method takes an `options` parameter of `TAnimationOptions` that defines the animation duration and EasingCurve, which can be `linear`, `ease-in`, `ease-out` or `ease-in-out`.

-   **Linear**: This function implies a constant rate of change. It means the animation proceeds at the same speed from start to end. There's no acceleration or deceleration, giving a very mechanical feel.
-   **Ease-in**: This function causes the animation to start slowly and then speed up as it progresses. Initially, there's gradual acceleration, and as the function moves forward, the rate of change increases.
-   **Ease-out**: Contrary to ease-in, ease-out makes the animation start quickly and then slow down towards the end. It begins with a faster rate of change and gradually decelerates.
-   **Ease-in-out**: This function combines both ease-in and ease-out. The animation starts slowly, speeds up in the middle, and then slows down again towards the end. It offers a balance of acceleration and deceleration.

The code samples below displays a custom Marker when the map is first clicked. When the map is clicked again, the Marker is animated to the clicked location using the default animation options.


  
    
```tsx
    export default function AnimatedMarkers() {
      const { mapData } = useMap();
      const [markerCoordinate, setMarkerCoordinate] = useState<Mappedin.Coordinate | null>(
        mapData?.mapCenter || null
      );

      // handle map clicks to update the marker's coordinate
      useMapViewEvent("click", (event) => {
        setMarkerCoordinate(event.coordinate);
      });

      // render <AnimatedMarker/> with updated coordinates
      return (
        <>
          {markerCoordinate && (
            <AnimatedMarker
              target={markerCoordinate}
              duration={1000}
              options={{ interactive: true, anchor: "right" }}
            >
              <img
                src="https://k2mgpc.csb.app/logo.png"
                alt="Marker"
                style={{
                  width: "25px",
                  position: "relative",
                  top: "-10px",
                  left: "-13px",
                }}
              />
            </AnimatedMarker>
          )}
        </>
      );
    }
    ```


  
  
    
```ts
    let marker;
    mapView.on('click', async (event) => {
      if (marker) {
        mapView.Markers.animateTo(marker, event.coordinate);
      } else {
        marker = mapView.Markers.add(
          event.coordinate,
          'Marker',
          {
            interactive: true,
            anchor: 'right'
          }
        );
      }
    });
    ```

  



## Enabling and Disabling Markers

Markers can be dynamically enabled or disabled using MapViewControl.updateState() or the `enabled` property of Mappedin.TAddMarkerOptions.enabled. When a marker is disabled, it will be hidden from view but remain in the map's memory. This is useful for managing marker visibility based on conditions like zoom level or user interaction, without the overhead of repeatedly adding and removing markers.

Use MapViewControl.getState() to check a marker's current state, which returns the marker's current properties including its enabled status.

Here's an example on how to enable/disable markers on click:


  
    
```tsx
    const [isEnabled, setIsEnabled] = useState(true);
    const space = mapData?.getByType("space")[14];

    useMapViewEvent("click", (event) => {
      setIsEnabled(!isEnabled);
    });

    return (
      <Marker
        target={space}
        options={{
          enabled: isEnabled,
          interactive: true
        }}
      >
        <div className="markerContainer">
          Click to enable/disable marker
        </div>
      </Marker>
    );
    ```


  
  
    
```ts
    let coordinate;
    let marker;
    mapView.on("click", async (event) => {
        // first click - add marker
        if (!marker) {
            console.log("Adding marker at:", event.coordinate);
            coordinate = event.coordinate;
            marker = mapView.Markers.add(
                coordinate,
                "<div class='markerContainer'>Enabled Marker!</div>"
            );
        } else {
            // get current state of marker
            const markerState = mapView.getState(marker);
            console.log("Current Marker State:", markerState);

            // toggle enabled state
            const newState = !markerState.enabled;
            mapView.updateState(marker, { enabled: newState });
            console.log(`Marker is now ${newState ? "enabled" : "disabled"}`);
        }
    });
    ```


  



A common use case is showing different sets of markers based on zoom level:


 
    
```tsx
    const spaces = mapData.getByType('space')
    const [secondaryMarkers, setSecondaryMarkers] = useState(
      spaces.slice(5).map(space => ({
        target: space,
        text: space.name,
        enabled: false
      }))
    );

    useMapViewEvent('camera-change', (transform) => {
      setSecondaryMarkers(markers =>
        markers.map(marker => ({
          ...marker,
          enabled: transform.zoomLevel >= 20
        }))
      );
    });

    return (
      <>
        {/* primary markers - always visible */}
        {spaces.slice(0, 5).map(space => (
          <Marker
            key={space.id}
            target={space}
            text={space.name}
            options={{ enabled: true }}
          />
        ))}

        {/* secondary markers - conditionally visible */}
        {secondaryMarkers.map(marker => (
          <Marker
            key={marker.target.id}
            target={marker.target}
            text={marker.text}
            options={{ enabled: marker.enabled }}
          />
        ))}
      </>
    );
    ```


  
  
    
```ts
    // create two sets of markers from spaces
    const primaryMarkers = mapData
      .getByType("space")
      .filter((space) => space.name !== "")
      .slice(0, 40)
      .map((space) =>
        mapView.Markers.add(
          space,
          `<div class="markerContainer">Primary: ${space.name}</div>`,
          { interactive: true, enabled: true }
        )
      );

    // add & store secondary markers with references
    const secondaryMarkers = mapData
      .getByType("space")
      .filter((space) => space.name !== "")
      .slice(40, 60)
      .map(async (space) => {
        const marker = await mapView.Markers.add(
          space,
          `<div class="markerContainer markerSecondary">Secondary: ${space.name}</div>`,
          { interactive: true }
        );
        marker.markerInstance = markerObject; // store reference
        mapView.updateState(marker, { enabled: false }); // init hide secondary markers
      });

    // update marker visibility based on zoom level
    mapView.on("camera-change", (transform) => {
      if (transform.zoomLevel < 19) {
        secondaryMarkers.forEach((marker) => {
          if (marker.markerInstance) {
            mapView.updateState(marker.markerInstance, { enabled: false });
          }
        });
      } else {
        secondaryMarkers.forEach((marker) => {
          mapView.updateState(marker.markerInstance, { enabled: true });
        });
      }
    });
    ```


  



> A complete example demonstrating markers can be found in the Mappedin React Native Github repo: markers.tsx

### Migration Guide

# Migration Guide

Mappedin SDK for React Native version 6.0 is a major release that includes a number of changes to the SDK. Mappedin SDK for React Native v6 uses a GeoJSON-based rendering engine, rebuilt from the ground up. It works in unison with MapLibre which enables outdoor base maps as well as data visualization features. By using GeoJSON as the core data format, v6 can integrated with existing external data sources. This guide explains the steps needed to migrate from version 5.

## Support for Declarative Components

Mappedin SDK for React Native v6 supports declarative components. This means that you can use the MapView component to render the map and include child components such as Marker and Label. MapView replaces MiMapView. Refer to the Getting Started Guide for more information on how to use declarative components.

Imperative components are still supported.

## New Hooks

### Hook to access MapView and MapData

Mappedin SDK for React Native v6 includes new hooks to access the MapView, Mappedin.MapData and Mappedin.TEvents.

### Hook for Events

Mappedin SDK for React Native v6 introduces a new event system. This means that you can use the useEvent hook to subscribe to events and trigger a callback when they occur.

Example of handling a `click` event:

v5


```ts
onClick={({ payload }) => {
  // The user clicked.
}}
```


v6


```tsx
  useMapViewEvent("click", (payload: Mappedin.TClickPayload) => {
    // The user clicked.
  });
```


## Initialization Changes

The options for getting a map have changed.

v5 Initialization


```ts
const venueOptions: TGetVenueOptions = {
  venue: VENUE,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
};

const RenderMap = () => {
  return (
    <SafeAreaView style={styles.fullSafeAreaView}>
      <MiMapView style={styles.mapView} key="mappedin" options={venueOptions} />
    </SafeAreaView>
  );
};
```


v6 Initialization


```ts
const App = () => {
  return (
    <View>
      <MapView
        mapData={{
          key: KEY,
          secret: SECRET,
          mapId: MAP_ID,
        }}
      options={{}}
      >
      </MapView>
    </View>
  );
};
```


## Component Access

`Mappedin.` has been replaced by `Mappedin.MapData.getByType()`

For example:

In v5 access nodes using `Mappedin.nodes`, which contains an array of `Node` objects.

In v6 access nodes using `MapData.getByType('node')`, which returns an array of `Node` objects.

`Mappedin.getCollectionItemById` is replaced by `Mappedin.MapData.getById(, id)`

The following classes have been redesigned. Refer to the chart below for a mapping of similar classes.

| v5 Component                                                                                                   | v6 Component                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| MappedinPolygon       | Mappedin.Space           |
| MappedinMapGroup     | Mappedin.FloorStack |
| MappedinMap               | Mappedin.Floor           |
| MappedinCoordinate | Mappedin.Coordinate |
| MappedinNode             | Mappedin.Node             |

MapViewStore.state no longer exists. These states are now available within their respective classes Mappedin.BlueDot.state and Mappedin.StackedMaps.state.

## UI Components

FloatingLabels have been replaced with Label (declarative) and Mappedin.Labels (imperative).

FloatingLabels.labelAllLocations() has been replaced with Labels.all().

`Tooltips` have not been carried over from v5 and Marker should be used instead.

## Updating UI Components

`setPolygonColor`, `clearPolygonColor` and other methods of changing the state of UI objects on the map is now performed using MapViewControl.updateState(), which also supports `initial` for returning properties to their original state.

`Mappedin.Camera.animate()` has been renamed to Mappedin.Camera.animateTo().

`Mappedin.Markers.animate()` has been renamed to Mappedin.Markers.animateTo().

## Interactivity

MapViewStore.addInteractivePolygon() has been replaced by updating the state of each space to be interactive as shown below.


```ts
// Set each space to be interactive.
mapData.getByType('space').forEach(space => {
    mapView.updateState(space, {
        interactive: true,
    });
});
```


Event names passed from `MapView.on()` have been changed and are now defined in Mappedin.TEvents.

| v5 Event                                                        | v6 Event              |
| --------------------------------------------------------------- | --------------------- |
| `E_SDK_EVENT.CLICK`                                             | `click`               |
| `E_SDK_EVENT.MAP_CHANGED , E_SDK_EVENT.MAP_CHANGED_WITH_REASON` | `floor-change`        |
| `E_SDK_EVENT.OUTDOOR_VIEW_LOADED`                               | `outdoor-view-loaded` |

## Map Metadata

Classes containing enterprise map metadata have been renamed.

| v5 Component                                                                                               | v6 Component                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| MappedinCategory | Mappedin.EnterpriseCategory |
| MappedinLocation | Mappedin.EnterpriseLocation |
| MappedinVenue       | Mappedin.EnterpriseVenue       |

## Wayfinding & Directions

`MappedinNavigatable.directionsTo()` is replaced by MapViewControl.getDirections().

MapViewControl.getDirections() only supports getting directions between two locations. For multi destination directions, use MapViewControl.getDirectionsMultiDestination().

Journey is now Navigation.

v5 Multi Destination Directions


```ts
const directions = getDirections(start, [dest1, dest2]);
```


v6 Multi Destination Directions


```ts
const directions = getDirectionsMultiDestination(start, [dest1, dest2]);
```


## Camera

v5 `Camera.tilt` in radians is replaced by v6 Mappedin.Camera.pitch in degrees. `Camera.minPitch` and `Camera.maxPitch` are now available to set the minimum and maximum pitch values.

v5 `Camera.rotation` in radians is replace in v6 by Mappedin.Camera.bearing in degrees clockwise rotation is now positive.

v5 `Camera.zoom`, `Camera.minZoom` and `Camera.maxZoom` used meters from ground level. In v6 these now use mercator zoom level units.

The following camera methods and accessors have been renamed.

| v5 Method                                                                                                                                          | v6 Method                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Camera.position()`                                                                                                                                | Camera.center()                     |
| `Camera.setSafeAreaInsets()`                                                                                                                       | Camera.setScreenOffsets() |
| `Camera.getSafeAreaInsets()`                                                                                                                       | Camera.screenOffsets()       |
| MapView.Camera.on(...)                                                   | (...)                                   |
| E_CAMERA_EVENT.USER_INTERACTION_START | useMapViewEvent('user-interaction-start')              |
| E_CAMERA_EVENT.USER_INTERACTION_END     | useMapViewEvent('user-interaction-end')                |
| E_CAMERA_EVENT.CHANGED                               | useMapViewEvent('camera-change')                       |

## Search

OfflineSearch has been moved to Mappedin.MapData.search(). The results returned in SearchResult are more structured:


```ts
const results = mapData.Search.query('levis');
// results
{
	places: SearchResultPlaces[];
	enterpriseLocations?: SearchResultEnterpriseLocations[];
	enterpriseCategories?: SearchResultEnterpriseCategory[];
}
```


## Multi Language

The methods to work with maps in multiple languages have been changed.


```ts
// Specify a non default language when getting map data.
const options = {
    key: 'key',
    secret: 'secret',
    mapId: 'mapId',
    language: 'en',
};
// Get supported languages.
const supportedLanguages = mapData.getByType('enterprise-venue')[0].languages;
// Change languages
await mapData.changeLanguage('es');
```


## Blue Dot


In Mappedin SDK for React Native v5, the Blue Dot controller was always available as part of the MapView. Now, Blue Dot is a separate package which must be installed and initialized separately.

With NPM:


```bash
npm install @mappedin/blue-dot
```


With Yarn:


```bash
yarn add @mappedin/blue-dot
```


Enabling Blue Dot:

v5


```ts
mapView.BlueDot.enable();
```


v6

```ts
import { BlueDot } from '@mappedin/blue-dot';

// Create a new BlueDot instance with the MapView
const blueDot = new BlueDot(mapView);

// Enable the Blue Dot with custom options
blueDot.enable({
  color: 'tomato',
  debug: true,
  accuracyRing: {
    color: 'forestgreen',
    opacity: 0.1,
  },
  heading: {
    color: 'aqua',
    opacity: 1,
  },
  inactiveColor: 'wheat',
  timeout: 20000,
});

// When no longer needed, disable the Blue Dot
blueDot.disable();
```


Handling of Blue Dot events has changed.

v5


```ts
const blueDotChangeHandler = ({ map, nearestNode, position, bearing }) => {
    // Do something with the new values
};
mapView.BlueDot.on(E_BLUEDOT_EVENT.POSITION_UPDATE, blueDotChangeHandler);
```


v6


```ts
// Position update
blueDot.on('position-update', e => {
    console.log('position-update', e.coordinate, e.floor, e.accuracy, e.heading);
});

// State change
blueDot.on('state-change', e => {
    console.warn('state-change', e.state, e.action);
});

// Error
blueDot.on('error', e => {
    console.error('error', e);
});
```


`BlueDot.updateBearing()` functionality has been moved to the Mappedin.BlueDot.update() method and is provided using the `heading` property. In v6, to remove the heading unset it in the `update` method as shown below, otherwise it will use the heading provided from the browser.


```ts
mapView.BlueDot.update({ heading: undefined });
```


`PositionUpdater` has been removed. The same functionality can be achieved by calling `BlueDot.enable({ watchBrowserPosition: false })` and then calling the Mappedin.BlueDot.update() method.

Blue Dot rotation mode was set when enabling Blue Dot in v5 using TEnableBlueDotOptions.useRotationMode. In v6, this is set by calling Mappedin.BlueDot.follow and setting the Mappedin.TFollowMode.

The v5 behavior of TEnableBlueDotOptions.allowImplicitFloorLevel has changed. In v5 it assumed the user was always on the default map if no level update was provided by the indoor positioning provider. In v6, if the floor cannot be determined Blue Dot will render on every floor by default. If the position update has a `floorLevel`, it will only render on that floor. To force it to render on all floors set `floorOrFloorId` to `undefined`:


```ts
mapView.BlueDot.update({ floorOrFloorId: undefined });
```


Blue Dot smoothing has not been carried over from v5.

### Multi Floor View & Stacked Maps

# Multi Floor View & Stacked Maps

> 

> 

## Multi Floor View

Multi Floor View is a feature that displays all floors in a building stacked vertically below the active floor, allowing users to see the building's vertical structure and navigate between floors. The active floor is fully rendered while lower floors appear as semi-transparent footprints.

!MultiFloor View

Multi Floor View is enabled by default. It can be controlled using the `multiFloorView` option when initializing the map view as shown in the code sample below. In this example, the map view is initialized with the `initialFloor` set to `m_952cd353abcb1a13`, which is ID of the 10th floor of the building. Other Multi Floor View options are defined in TMultiFloorViewOptions and include the ability to set the gap between floors as well as whether the camera should move when the active floor changes.

### Code Sample


```tsx
return (
  <View style={[mapStyles.container, style]}>
    <MappedInView
      options={{
        initialFloor: "m_952cd353abcb1a13",
        multiFloorView: {
          enabled: true,
          floorGap: 10,
          updateCameraElevationOnFloorChange: true,
        },
      }}
      mapData={{
        key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
        secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
        mapId: "67a6641530e940000bac3c1a",
      }}
    >
      {children || <MapSetup />}
    </MappedInView>
  </View>
);
```


It is possible to set multiple floors to be visible at once, which can be useful for overlaying data within the building, such as the locations of security cameras or other assets. This can be done by setting the visible property to true for each floor that should be shown, using TFloorUpdateState as shown in the code sample below.


```ts
// Show the 6th floor as well.
const floor = mapData.getByType("floor").find((f) => f.elevation === 6);
mapView.updateState(floor, {
  geometry: { visible: true },
});
```


When displaying multiple floors, by default content such as labels, markers, paths and images are only visible on the active floor. These can be displayed on additional visible floors by enabling them for the floor using TFloorUpdateState as shown below.


```ts
mapView.updateState(floor, {
  visible: true,
  altitude: 0,
  geometry: {
    visible: true,
  },
  images: { enabled: true },
  labels: { enabled: true },
  markers: { enabled: true },
  paths: { enabled: true },
});
```


## Stacked Maps

Stacked Maps consist of individual layers that represent different floors of a multi-story building. These layers are conceptually or digitally stacked to create a complete view of the structure, allowing users to visualize, navigate, and interact with multiple floors in an integrated way.

!Stacked Maps

Stacked Maps can be enabled by setting the visibility of floors that should appear in the stack to `true` and altering their altitude defined in TFloorUpdateState, so that each floor is raised above the previous floor. There are two ways to modify the visibility and altitude of a floor:

1. MapViewControl.animateState() gradually moves the floor to the new altitude over a specified duration of time.
2. MapViewControl.updateState() instantly snaps the floor to the new altitude.

Alternative visualization methods can also be created by using variations of this technique. For example, an app may wish to only show the top and bottom floors of a building, or only show the floors that are currently accessible to the user by setting the visibility of the floors to `true` or `false` based on the app's requirements.

When displaying multiple floors, by default content such as labels, markers, paths and images are only visible on the active floor. These can be displayed on additional visible floors by enabling them for the floor using TFloorUpdateState as shown below.


```ts
mapView.updateState(floor, {
  images: { enabled: true },
  labels: { enabled: true },
  markers: { enabled: true },
  paths: { enabled: true },
});
```


When using Stacked Maps with Dynamic Focus or Navigation, the `MapViewControl.manualFloorVisibility` property should be set to `true` to ensure that the floors remain visible. Otherwise they could be hidden by the Dynamic Focus or Navigation features, which by default will hide all floors that are not the active floor.

### Code Sample

The following code sample shows how to enable Stacked Maps by setting the visibility of all floors to `true` and altering their altitude. Two methods are provided to expand and collapse the stacked maps view. Each method provides the option to use `animateState` or `updateState` to alter the altitude of the floors. It also puts the camera in elevation mode when expanding the floors and returns to default mode when collapsing the floors, which makes it easier for the user to move up and down to see the floors.


```ts
import { Floor, TCameraAnimationOptions } from "@mappedin/react-native-sdk";

export type TExpandOptions = TCameraAnimationOptions & {
  distanceBetweenFloors?: number;
  cameraPanMode?: "default" | "elevation";
};

export function expandFloors(
  mapView: any,
  mapData: any,
  options?: TExpandOptions
) {
  const distanceBetweenFloors = options?.distanceBetweenFloors ?? 10;
  mapView.Camera.setPanMode(options?.cameraPanMode ?? "elevation");
  mapView.manualFloorVisibility = true;

  mapData.getByType("floor").forEach((floor: Floor) => {
    const newAltitude: number = floor.elevation * distanceBetweenFloors;
    const isCurrentFloor = floor.id === mapView.currentFloor.id;

    const currentState = mapView.getState(floor);
    if (currentState) {
      if (!currentState.visible || !currentState.geometry.visible) {
        mapView.updateState(floor, {
          visible: true,
          altitude: 0,
          geometry: {
            visible: true,
            opacity: isCurrentFloor ? 1.0 : 0.0,
          },
        });
      }
    }

    if (options?.duration ?? 0 > 0) {
      mapView.animateState(
        floor,
        {
          altitude: newAltitude,
          geometry: {
            opacity: 1.0,
          },
        },
        {
          duration: options?.duration ?? 0,
          easing: options?.easing ?? "ease-in-out",
        }
      );
    } else {
      mapView.updateState(floor, {
        altitude: newAltitude,
        visible: true,
        geometry: {
          visible: true,
          opacity: 1.0,
        },
      });
    }
  });
}

export function collapseFloors(
  mapView: any,
  mapData: any,
  options?: TCameraAnimationOptions
) {
  mapView.Camera.setPanMode("default");
  mapView.manualFloorVisibility = false;

  mapData.getByType("floor").forEach((floor: any) => {
    const isCurrentFloor = floor.id === mapView.currentFloor.id;
    if (options?.duration ?? 0 > 0) {
      mapView.animateState(
        floor,
        {
          altitude: 0,
          geometry: {
            opacity: isCurrentFloor ? 1.0 : 0.0,
          },
        },
        {
          duration: options?.duration ?? 0,
          easing: options?.easing ?? "ease-in-out",
        }
      );
      setTimeout(() => {
        mapView.updateState(floor, {
          visible: isCurrentFloor ? true : false,
          altitude: 0,
          geometry: {
            visible: isCurrentFloor ? true : false,
            opacity: isCurrentFloor ? 1.0 : 0.0,
          },
        });
      }, options?.duration ?? 0);
    } else {
      mapView.updateState(floor, {
        altitude: 0,
        visible: isCurrentFloor ? true : false,
        geometry: {
          visible: isCurrentFloor ? true : false,
          opacity: 1.0,
        },
      });
    }
  });
}
```

### Outdoor Map

# Outdoor Map

> 

> 

The outdoor map shown around the Mappedin indoor map can be manipulated to show or hide additional information. It can be used to add GeoJSON based geometry, images, deck.gl layers and more.

The outdoor map is accessed using MapViewControl.Outdoor.map, which returns a `maplibregl.Map` object. MapLibre GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. Mappedin SDK for React Native makes use of it to display the outdoor map.

By providing access to the MapLibre map used to draw the outdoor map, Mappedin SDK for React Native enables developers to draw on and manipulate the outdoor map. Developers can use most capabilities of MapLibre GL JS with key exceptions being Interactivity and Camera, which are not available.

> User touch and click events are handled by Mappedin SDK for React Native and are not propagated to the outdoor map layer. Camera movement is also handled by Mappedin SDK for React Native and cannot be manipulated using MapLibre controls.

The remainder of this guide demonstrates a few examples of what could be achieved with the outdoor map. Please refer to the MapLibre GL JS documentation and MapLibre GL JS Examples for comprehensive instructions and demonstrations of what is possible with MapLibre.

## Styles

Styles can be applied to the outdoor map to change its colors. Mappedin provides five pre-built styles to choose from.

-   Default: https://tiles-cdn.mappedin.com/styles/mappedin/style.json
-   Honeycrisp: https://tiles-cdn.mappedin.com/styles/honeycrisp/style.json
-   Fresh Mint: https://tiles-cdn.mappedin.com/styles/freshmint/style.json
-   Night Blue: https://tiles-cdn.mappedin.com/styles/midnightblue/style.json
-   Starlight: https://tiles-cdn.mappedin.com/styles/starlight/style.json

To change the style used by the Outdoor map, pass the URL of the style in the outdoorView object of Mappedin.TShow3DMapOptions as shown below.


```tsx
<MapView
  mapData={{
    key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
    secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
    mapId: "660c0c3aae0596d87766f2da",
  }}
  options={{
    outdoorView: {
      style: 'https://tiles-cdn.mappedin.com/styles/freshmint/style.json',
    },
  }}
>
</MapView>
```


The outdoor style can also be changed at runtime using MapViewControl.Outdoor.setStyle().


```ts
mapView.Outdoor.setStyle('https://tiles-cdn.mappedin.com/styles/freshmint/style.json');
```


## Adding Raster or Vector Maps

Mappedin SDK for React Native's outdoor map uses a road map to provide users with a reference point and to give them context of the area around buildings. An app may wish to display a different type of map, such as a satellite image or weather patterns.

Mappedin SDK for React Native allows an app to add additional map sources. Vector, raster and raster-dem sources can be used from providers such as Google, Azure, MapTiler or mapbox.

### Satellite Outdoor Map

The following Mappedin JS example demonstrates the use of a raster satellite image source from MapTiler.

> The key used in this example is locked for use on developer.mappedin.com and the provided CodeSandbox. To customise this example, create a free MapTiler key at https://www.maptiler.com/



### Adding a Raster Source

The following code snippet adds a raster satellite map from MapTiler. The `addLayer` method passes `mappedin` as the name of the layer to draw below. This ensures that the layer is drawn under the indoor map. Remove it if you need to have your source rendered on top of the indoor map.


```ts
const { mapView } = useMap();
// On load of the outdoor map, add a satellite tiles layer
useEffect('outdoor-view-loaded"', () => {
    try {
        // Add a raster tile source for satellite imagery from MapTiler.
        // Get your own free MapTiler key at https://www.maptiler.com/
        mapView.Outdoor.map.addSource('satelite', {
            type: 'raster',
            tiles: [
                'https://api.maptiler.com/maps/satellite/{z}/{x}/{y}@2x.jpg?key=<REPLACE_WITH_YOUR_KEY>',
            ],
            tileSize: 512,
            attribution: '© MapTiler © OpenStreetMap contributors',
        });

        // Add a raster layer using the satellite source.
        // Have it show below the mappedin layer, which holds the indoor map.
        mapView.Outdoor.map.addLayer(
            {
                id: 'satelite',
                type: 'raster',
                source: 'satelite',
                paint: {},
            },
            'mappedin'
        );
    } catch (error) {
        console.error('Error adding tile source or layer:', error);
    }
});
```


### Adding a Vector Source

The following code snippet adds a contour vector map from MapTiler. The `addLayer` method passes `mappedin` as the name of the layer to draw below. This ensures that the layer is drawn under the indoor map. Remove it if you need to have your source rendered on top of the indoor map.


```ts
const { mapView } = useMap();
// On load of the outdoor map, add a satellite tiles layer
useEffect('outdoor-view-loaded"', () => {
    try {
        // Add a vector tile source for satellite imagery from MapTiler.
        // Get your own free MapTiler key at https://www.maptiler.com/
        mapView.Outdoor.map.addSource('contours', {
            type: 'vector',
            url: 'https://api.maptiler.com/tiles/contours/tiles.json?key=<REPLACE_WITH_YOUR_KEY>',
        });

        // Add a raster layer using the satellite source.
        // Have it show below the mappedin layer, which holds the indoor map.
        mapView.Outdoor.map.addLayer(
            {
                id: 'terrain-data',
                type: 'line',
                source: 'contours',
                'source-layer': 'contour',
                layout: {
                    'line-join': 'round',
                    'line-cap': 'round',
                },
                paint: {
                    'line-color': '#ff69b4',
                    'line-width': 1,
                },
            },
            'mappedin'
        );
    } catch (error) {
        console.error('Error adding tile source or layer:', error);
    }
});
```


## Drawing GeoJSON Geometry on the Outdoor Map

MapViewControl.Outdoor.map allows drawing GeoJSON based geometry on top of the outdoor map using MapLibre. The following example demonstrates drawing a LineString on the outdoor map that represents an area under construction that should be avoided. Labels are drawn using Mappedin APIs.



## 3D Buildings

Outdoor Street Maps (OSM), which are used to create the outdoor map contain height and shape information for many buildings. This data can be used to render 3D buildings on the outdoor map. The example below demonstrates how to do this. A `3d-building` layer is added, which extrudes buildings based on their height in OSM. Then a filter is applied to the `3d-building` layer to avoid drawing the 3D building located at the indoor map location, preventing the indoor map from being obscured.


```ts
import { useMap } from '@mappedin/react-sdk';
import { useRef } from 'react';

export function ThreeDBuildings() {
    const { mapView } = useMap();
    const stylesheetId = useRef('');

    // Get an instance of the MapLibre outdoor map.
    const outDoorMap = mapView.Outdoor.map;

    // Once the outdoor map is loaded, load the 3D buildings.
    useEffect('outdoor-view-loaded"', () => {
        const layers = map.getStyle().layers;
        const buildingLayer = layers.find((layer: { id: string }) => layer.id === 'building');
        const color = buildingLayer?.paint?.['fill-color'];
        //Add the 3d-building layer above the mappedin layer.
        outDoorMap.addLayer(
            {
                id: '3d-building',
                source: 'osm',
                'source-layer': 'building',
                type: 'fill-extrusion',
                minzoom: 15,
                paint: {
                    'fill-extrusion-color': color,
                    'fill-extrusion-height': ['get', 'render_height'],
                    'fill-extrusion-base': ['get', 'render_min_height'],
                },
            },
            'mappedin'
        );
    });

    // Filter the indoor map's building from the 3D buildings that
    // are drawn. This prevents the indoor map from being covered.
    outDoorMap.on('styledata', e => {
        if (
            outDoorMap &&
            e &&
            e.dataType === 'style' &&
            e.type === 'styledata' &&
            outDoorMap.getLayer('3d-building')
        ) {
            // If we can find the id we'll use it, otherwise assume it has changed.
            const newStylesheetId = e?.style?.stylesheet?.id;
            if (!newStylesheetId || newStylesheetId !== stylesheetId.current) {
                stylesheetId.current = newStylesheetId;
                outDoorMap.setFilter('3d-building', outDoorMap.getFilter('building'));
            }
        }
    });

    return null;
}
```


The CodeSandbox below shows this example in action.



## Using deck.gl

In addition to using MapLibre methods, deck.gl can also be used to draw on the outdoor map using `deck.MapboxOverlay`. The next example shows how to take positional information in GeoJSON format that represents the off site positions of shopping carts and displays them on the map using a deck.gl `ScatterplotLayer`.



## Drawing an Image on the Outdoor Map

Images can be drawn on top of the outdoor map. They are positioned using latitude and longitude coordinates that begin on the top left position and continue clockwise. The example below draws an image of a black parking symbol. The green parking symbol uses an image on a Marker created with Mappedin APIs.

Right click on the map and move to rotate it to observe how the image added to the outdoor map remains static while the image added to a Marker rotates with the map to always use the same perspective. The Marker also remains a constant size when the map is zoomed in and out while the image gets smaller and larger.

### Points of Interest

# Points of Interest

> 

> 

Points of Interest (POIs) are specific locations or features on a map that users find useful or informative. POIs serve as landmarks or markers, highlighting key places, services, or objects to enhance the map's utility and user experience.

> A complete example demonstrating POIs can be found in the Mappedin React Native Github repo: pois-demo.tsx

They are contained in the Mappedin.PointOfInterest class, which contains a coordinate, name, description, images, links and the floor the point of interest exists on. All of these elements are configured in the Mappedin Editor.

!Mappedin JS v6 POIs

Mappedin.PointOfInterest.name could be used to create labels to show users helpful information. The code sample below creates a label at the location of each Mappedin.PointOfInterest and uses its name as the label text. It also verifies that the Mappedin.PointOfInterest exists on the current floor being shown in the MapView.


  
    
```tsx
    // Get all points of interest
    const pois = mapData.getByType('point-of-interest');

    // Create labels for each point of interest
    return (
      <>
        {pois.map(poi => (
          <Label
            key={poi.externalId}
            target={poi}
            text={poi.name}
          />
        ))}
      </>
    );
    ```


  



```ts
// Iterate through each point of interest and label it.
for (const poi of mapData.getByType('point-of-interest')) {
	// Label the point of interest if it's on the map floor currently shown.
	if (poi.floor.id === mapView.currentFloor.id) {
		mapView.Labels.add(poi.coordinate, poi.name);
	}
}
```




> A complete example demonstrating POIs can be found in the Mappedin React Native Github repo: pois-demo.tsx

### Release Notes

# Release Notes

Mappedin SDK for React Native v6 release notes are posted here and this page will be kept up-to-date as updates are released. The SDK is available from @mappedin/react-native-sdk on NPM.

{

// Release notes template:

// https://keepachangelog.com/en/1.0.0/#how

// ## vXX.XX.XX - Month Day, Year
// _ Added
// _ Changed
// _ Deprecated
// _ Removed
// _ Fixed
// _ Security

}
## v6.0.0-rc.5

### Breaking Changes

#### ⚠️ State Management API Update
**Change**: `getState()` and `updateState()` methods no longer accept entity ID directly as a parameter

**Before**:

```js
mapView.getState('entity-id-123')
mapView.updateState('entity-id-123', newState)
```


**Now**:

```js
const entity = mapView.getById('space', id)
mapView.getState(entity)
mapView.updateState(entity, newState)
```


**Why**: Improves API consistency and type safety across the SDK

### Bug Fixes

#### React Native Web Improvements
- **Input Focus Issue**: Fixed React Native web examples where input fields were losing focus during user interaction
- **State Hydration**: `updateState()` now correctly processes state objects for hydration and deserialization
- **Iframe Serialization**: React Native web messaging with iframe now properly serializes/deserializes data, resolving `directions.draw` functionality

#### Dependency Management
- Fixed peer dependency issue. Now react-native correctly peer depend on the corresponding @mappedin/mappedin-js version. Currently `v6.0.0-rc.5`

### Documentation

- **React Native & React Integration**: Added `@mappedin/mappedin-js` documentation to React Native and React SDK guides for improved developer experience

## v6.0.0-beta.1

### Features

#### 🔵 React Native SDK now supports `useBlueDot` hook extension

```tsx
import { MapView } from '@mappedin/react-native-sdk';
import { useBlueDot } from '@mappedin/blue-dot';

function MyComponent() {
  const { enable, isReady, state, following } = useBlueDot()

  // Use the Blue Dot API
  React.useEffect(() => {
    if (isReady) {
      enable({ radius: 15, color: '#ff0000' });
    }
  }, [isReady]);
}

```


#### 🚀 New api `mapView.getInView('label')` supports getting label that's in the viewport

### Breaking Changes

- Rename Images to Image3D and Image to Image3DView
- `mapView.Query.nearest`  is now async and added travel mode to Query.nearest for fast searching of features around a coordinate.

### Bug fixes

- fixed an issue mapData language option is not respected


## v6.0.0-beta.0

### Features

**Breaking Change**: `useDynamicFocus` hook moved to dedicated package
- **Before**: Imported from `@mappedin/react-native-sdk`
- **Now**: Import from `@mappedin/dynamic-focus`
- **Why**: React Native SDK now supports our extension system architecture

**Usage:**


```tsx

import { MapView } from '@mappedin/react-native-sdk';
import { useDynamicFocus } from '@mappedin/dynamic-focus';

function MyComponent() {
  const { updateState, isReady } = useDynamicFocus();

  // Use the Dynamic Focus API
  React.useEffect(() => {
    if (isReady) {
      updateState({ autoFocus: true });
    }
  }, [isReady]);
}
```


### Breaking Change
- rename useEvent to useMapViewEvent
- Remove useDynamicFocus hook
- Add `@mappedin/mappedin-js` as peer dependency
- removed `useDynamicFocus` in favour of extension

## v6.0.0-alpha.14

_Aug 28, 2025_

### Features
- **React Native SDK Browser Support**: The React Native SDK can now run directly in browser environments.
- **Introduced new `path.width` property**: short hand for `pathOptions.nearRadius`, `pathOptions.farRadius`, `pathOptions.nearZoom`, `pathOptions.farZoom`

```ts
mapView.updateState(path, {
	on: 'zoom-level',
	input: [17, 18],
	output: [1, 2],
	easing: 'ease-in',
});
```


### Breaking Changes
- **Marker API Update**: Renamed `marker.anchor` to `marker.placement`
- **Experimental Labels**: Renamed `mapView.Labels.auto` to `mapView.Labels.__EXPERIMENTAL__auto` to reflect its status
- **BlueDot Deprecation**:
  - `mapView.BlueDot` is now deprecated
  - Temporary access available via `mapView.__BlueDot`
  - Will be moved to separate package in future release

### Bug Fixes
- **EU Environment Loading**: Resolved issue preventing `mapData` loading in `eu` environment
- **Deep API Calls**: Fixed nested API calls (2+ levels deep) - `mapView.Camera.interactions.set()` now works correctly


## v6.0.0-alpha.13

_July 21, 2025_

### Features

#### Dynamic Focus Hook
New `useDynamicFocus` hook to RN user to utilize the @mappedin/dynamic-focus package.

```tsx
const dynamicFocus = useDynamicFocus();
dynamicFocus.enable();
```


#### Offline Map Support
Load maps without internet connectivity by passing pre-hydrated map data to `` component

```tsx
const mapData = await hydrateMapData(mvf);
<MapView mapData={mapData} />
```


#### Offline 3D Models
Support for offline GLB and GLTF files (base64 encoded)

```tsx
<Models url={base64EncodedModelUri} />
```


#### Smaller & Cleaner WaterMark
Smaller, icon-only Mappedin watermark for cleaner map displays

## v6.0.0-alpha.12 - June 30, 2025

-   Initial release.

### Spaces

# Spaces

> 

> 

A Mappedin.Space represents an area enclosed by walls, such as a hall or room. Spaces can be Interactive and have Labels and Markers added to them. Spaces can also be customized with a color, texture and hover color.

## Spaces Example

The example below loops through all spaces and sets the color and hover color to a random color and makes them interactive. Hover over a space to see its color shown in the top left color field. Right clicking on any space will reset the spaces colors to default. Left clicking will randomly set new colors.

Refer to the Textures & Colors section for more information on how to set the texture or color of a space.


```ts
mapData.getByType('space').forEach((space) => {
	// Generate a random color
	const hexColor =
		'#' +
		Math.floor(Math.random() * 16777215)
			.toString(16)
			.padStart(6, '0');
	// Apply it to each space
	mapView.updateState(space, {
		color: hexColor, // Set the space's color to a random color
		interactive: true, // Make the space interactive (clickable and hoverable)
		hoverColor: hexColor, // Set the same value as hover color
	});
});
```


## Doors

By default, a Mappedin.Door is not visible and drawn as a gap in a wall. An app can set the `visible` property to `true` to make the door visible. Other properties of a door can also be set, such as color, texture, interactivity and more. Refer to Mappedin.TDoorsState for the complete list of properties. Refer to the Textures & Colors section for more information on how to set the texture or color of a door.

Doors are grouped into Mappedin.DOORS.Interior and Mappedin.DOORS.Exterior doors, based on whether they are on an interior or exterior wall.


```ts
//Make interior doors visible and brown.
mapView.updateState(DOORS.Interior, {
	visible: true,
	color: '#5C4033',
	opacity: 0.6,
});

//Make exterior doors visible and black.
mapView.updateState(DOORS.Exterior, {
	visible: true,
	color: 'black',
	opacity: 0.6,
});
```


The screenshot below shows brown interior and black exterior doors with labels added to depict the status of the door. To try the full interactive example, load the Door Status example in the Mappedin Showcase.

!Visible Doors

### Views

# Views

> 

> 

A `view` is a copy of a map that allows a map editor to toggle the visibility of a layer or individual items in a layer on and off and choose a map theme. It is similarly named but should not be confused with the `MapView` class, which is used to show a map.

Views allow the same map to be used for many use cases, such as:

-   Public use for wayfinding
-   Use one of many light or dark themes
-   With safety annotations for safety and security personnel
-   Showing private areas for maintenance and custodial staff
-   Displaying only the floor plan for leasing prospects
-   Highlighting delivery doors for delivery drivers
-   and many more...

## Get a View ID

A `viewId` is used by Mappedin JS to download specific view. To get a `viewId`:

1. Log into the Mappedin Editor.
2. Click on the `Developers` tab.
3. Select the desired map from the map drop down.
4. Select the desired view from the view drop down.
5. The `viewId` will be shown in the code snippet on the page.

## Display a View

To display a specific view of a map, specify the `viewId` of the view using the Mappedin.TGetMapDataSharedOptions object that is a property of MapViewProps used by MapView component.


```tsx
<MapView
  mapData={{
    key: KEY,
    secret: SECRET,
    mapId: MAP_ID,
    viewId: VIEW_ID,
  }}
  options={{}}
>
</MapView>
```


## View Example

The following example demonstrates how an app could display and switch between multiple views. Use the drop down menu to switch between the available views.

### Wayfinding

# Wayfinding

> 

> 

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.

!Mappedin JS v6 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 or not smooth. This is due to the SDK attempting to find the shortest path through the map's geometry. Directions can be smoothed by setting Mappedin.TGetDirectionsOptions.smoothing to true in the `Mappedin.TGetDirectionsOptions` passed to MapViewControl.getDirections().

## 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.


```ts
// 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 = 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.


```ts
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);
```


## 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. `nearRadius` and `farRadius` are described in the Path Styles section later in this guide.


```ts
useMapViewEvent('click', (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 = mapData.getDirections(clickedLocation, destination);

        if (directions) {
            // Navigate from the clicked location to the gymnasium.
            mapView.Navigation.draw(directions, {
                pathOptions: {
                    nearRadius: 1,
                    farRadius: 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 following image shows a map with multi-floor wayfinding using the Navigation class.

!Multi-floor wayfinding

## 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.

!Multi-destination wayfinding


```ts
// Pass an array of destinations to create multi-segment directions.
const directions = 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.


```ts
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.

!Path between two spaces

The width of the path is set using the `nearRadius` and `farRadius` parameters. These values are in meters. `nearRadius` is the path width used at the lowest zoom level closest to the ground and `farRadius` is used at the highest zoom level. Additional path styles are outlined later in this guide in the Path Styles section.


  
  
```ts
  // Get the directions between two spaces.
  const directions = mapData.getDirections(startSpace, endSpace);
  ```

  Then use the directions to draw a path.


```tsx
{
    directions && directions.coordinates && (
        <Path
            key="navigation-path"
            coordinate={directions.coordinates}
            options={{
                color: '#007AFF',
                nearRadius: 0.5,
                farRadius: 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');
            }}
        />
    );
}
```





```ts
// Get the directions between two spaces.
const directions = mapData.getDirections(startSpace, endSpace);
// Draw a path using the directions' coordinates array to show the route.
path = mapView.Paths.add(directions.coordinates, {
  nearRadius: 0.5,
  farRadius: 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.


```ts
// Remove a single path.
mapView.Paths.remove(path);
```



```ts
// Remove all paths
mapView.Paths.removeAll();
```


## Path Styles

Mappedin SDK for React Native offers many options to customise how paths appear to the user. Path animations, color, width and many more options can be set using Mappedin.TAddPathOptions.

## 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.

!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.


  
  
```ts
// Get directions from the first space to the second space.
const directions = mapData.getDirections(firstSpace, secondSpace);
  ```


Then use the directions to draw a path and add markers for each direction instruction.


```tsx
{
    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>`}
                />
            ))}
        </>
    );
}
```





```ts
// Get directions from the first space to the second space.
const directions = 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,
});
});

```




```