## version-6.0

### API Reference

# API Reference
## Latest Version


Mappedin SDK for React Native v6.0.0-alpha.12





## Previous Versions

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

> Mappedin SDK for React Native v6 is available as @mappedin/react-native-sdk@alpha 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
        options={{}}
        mapData={{
          key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
          secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
          mapId: "660c0c3aae0596d87766f2da",
        }}
      >
      </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 Mappedin.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} />;
    });
}
```


## useEvent

The useEvent 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([]);

    useEvent('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 useEvent 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
useEvent('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
useEvent('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
useEvent('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.

### 1. Create a Project

> Note that Mappedin SDK for React Native version 6 is currently in an alpha state. Therefore you must append @alpha 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 Typescripttemplate.


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


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


Using Yarn:


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


**Install Peer Dependencies**

This package requires the following peer dependencies:

Using NPM:


```bash
npm install react react-native react-native-webview
```


Using Yarn:


```bash
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
        options={{}}
        mapData={{
          key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
          secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
          mapId: "660c0c3aae0596d87766f2da",
        }}
      >
        <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.Images class is accessed through MapViewControl.Images 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.Images.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.

!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 useEvent 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.
  useEvent("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 useEvent 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.
  useEvent("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 useEvent 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 `useEvent("click"...` or `useEvent("hover"...` to capture click or hover events as shown below.


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

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

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

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

!Mappedin JS v6 Labels

## 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.iconVisibilityThreshold. A value below 0 will result in the icon always being hidden. Setting this value to 0 ensures icons show up at maxZoom (fully zoomed in) and 1 configures them to always be displayed.

## Label Appearance

Labels can have their appearance styled to match the visual theme of an app or to make groups of labels easily distinguishable from one another. The following type declaration of Mappedin.TLabelAppearance describes these customisable attributes.


```ts
interface TLabelAppearance {
    margin?: number;
    marker?: {
        backgroundColor?: { active?: string; inactive?: string };
        foregroundColor?: { active?: string; inactive?: string };
        icon?: string;
        iconFit?: "fill" | "contain" | "cover";
        iconOverflow?: "visible" | "hidden";
        iconPadding?: number;
        iconScale?: number | Interpolation<"zoom-level", number[]>;
        iconSize?: number;
        iconVisibleAtZoomLevel?: number;
    };
    text?: {
        backgroundColor?: string;
        foregroundColor?: string;
        lineHeight?: number;
        maxWidth?: number;
        numLines?: number;
        size?: number;
    };
}
```


### Mappedin.TLabelAppearance

Margin:

-   `margin` in pixels around the label and marker. This will affect label density.

Marker styles:

-   `backgroundColor` & `foregroundColor` The marker takes both `active` and `inactive` variants of its foreground and background colors.
-   `icon` is the SVG of icon to place inside a label.
-   `iconSize` is the size of the bounding box of the SVG icon.
-   `iconVisibilityThreshold` defines when the icon becomes visible relative to the current zoom level. Values should be between 0 and 1. 0 appears at maximum zoom and 1 causes the marker to always be shown.

Text styles:

-   `foregroundColor` and `backgroundColor` colors that can be set using CSS colors, as Hex strings or the CSS name of a color such as crimson.
-   `lineHeight` sets the height of a text line box. The default is 1.2.
-   `maxWidth` defines the maximum width of text in pixels.
-   `numLines` sets the maximum number of lines to display if the text spans multiple lines.
-   `size` is the text size in pixels.

The code sample below demonstrates how to use some label styling options. It specifies an SVG icon to use and sets the icon and text color. Labels are added to each space with a name.


```tsx
<Label
  key="sirens-label"
  target={sirenSpace}
  text={`🎵 Sirens`}
  options={{
    interactive: true,
    rank: "high",
    appearance: {
      text: {
        foregroundColor: "#E91E63",
      },
      marker: {
        foregroundColor: {
          active: "#4CAF50",
          inactive: "#999",
        },
        icon: "https://your-domain.com/icons/your-icon.svg",
      },
    },
  }}
  onLoad={(label) => {
    console.log("Sirens label loaded:", label);
  }}
/>
```


## Label Ranking

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

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


    
    
```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
    useEvent('click', event => {
        const newRank = (currentRank + 1) % RANKS.length; // Cycle through ranks
        setCurrentRank(newRank);

        const newLabel = {
            coordinate: event.coordinate,
            text: `Label Rank ${RANKS[newRank]}`,
            rank: RANKS[newRank],
        };

        setLabels(prevLabels => [...prevLabels, newLabel]);
    });

    return (
        <>
            {labels.map((label, index) => (
                <Label
                    key={index} // Use index as a fallback key for simplicity
                    target={label.coordinate} // Add the label to the clicked coordinate
                    text={label.text}
                    options={{
                        rank: label.rank, // Set the rank for the label
                    }}
                />
            ))}
        </>
    );
    ```


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

    useEvent('camera-change', (transform) => {
      setSecondaryLabels(labels =>
        labels.map(label => ({
          ...label,
          enabled: transform.zoomLevel >= 20
        }))
      );
    });

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

        {/* secondary labels - conditionally visible */}
        {secondaryLabels.map(label => (
          <Label
            key={label.target.id}
            target={label.target}
            text={label.text}
            options={{ enabled: label.enabled }}
          />
        ))}
      </>
    );
    ```


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

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

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

!Mappedin JS v6 Markers

## Creating Markers

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

	



## Anchors

Marker anchoring is set using the MarkerProps.options property. Options accepts a Mappedin.TAddMarkerOptions value, which has a member named `anchor`. When provided, the point of the Marker described by the anchor is placed next to the target. For example, using `center` will place the Marker's center at the target. Both a single anchor and an array of anchors can be provided. When an array is provided, the Marker is anchored to the first target that has space available to display the Marker. Anchor positions are defined in Mappedin.TMarkerAnchor which contains 9 values. The anchor points are as follows, with the default being center.

### TMarkerAnchor

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

Marker content can be styled using CSS that references the anchor 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-anchor='<ANCHOR>'];
```


Where `` is the anchor 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-anchor="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
    useEvent('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
      useEvent("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];

    useEvent("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
      }))
    );

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

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