Data layers

To add or update data layers, you should use the type-specific methods detiled in the next section, while other methods are shared between the layer types and documented further down.

Types of layers

Point layer

Coming soon — some methods are already present in the API but should not be used.

Polygon layer

A polygon layer has each data element rendered as an extruded polygon. It is useful to highlight rooms or specific zones in the buildings.

interface PolygonMapDataLayerDefinition {
  id: string,
  data: [{
    id: string,
    coordinates: [{
      levelIndex: number,
      x: number,
      z: number
    }] | [[{
      levelIndex: number,
      x: number,
      z: number
    }]],
    ...customData: object
  }],
  baseHeight?: number | (dataElement: object) => number,
  height?: number | (dataElement: object) => number,
  color?: string | (dataElement: object) => string,
  // + fields from SharedDefinitionOptions defined further down
}

map.addPolygonDataLayer(definition: PolygonMapDataLayerDefinition) => void
map.updatePolygonDataLayer(definitionUpdates: Partial<PolygonMapDataLayerDefinition>) => void

id is a unique identifier for this layer which is used for updates.
data is an array of objects (refered to as data elements) to be rendered. Each element must have an id (unique identifier within the data array) and a coordinates array. Elements can also contain any additional custom data used for rendering options.
- coordinates in its simple form is an array of points in the 2D horizontal space, it can also be an array of "rings" where the first ring is the external perimeter of the polygon, and the others are "holes" cut into the external perimeter.
baseHeight - optional - defines the elevation from the ground at the base of the polygon in meters. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the base height for that element. Default value: 0m.
height - optional - defines the height of the polygon in meters from its base to its top. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the height for that element. Default value: 3m.
color - optional - defines the color of the element to render. It can be defined as any valid CSS color string like "orange" or "#3a3c3c", and applied for all elements or per element with a function that takes each element as argument and returns the color string for that element. Default value: "#2393d4"
SharedDefinitionOptions are defined here.

Shared definition options

Some options correspond to generic behaviours that are shared by all data layers, making it easy to swap between similar layer types (e.g. "point" and "polygon").

// not an actual interface, this is simplified for documentation
interface SharedDefinitionOptions {
  tooltip?: (dataElement: object) => string | HTMLString,
  tooltipTemplate?: string,
  tooltipContainerStyle?: string,
  persistentTooltip?: boolean,
  legend?: LegendConfig, // see below
  onClick?: (dataElement: object, event: MapMouseEvent) => void,
  onHover?: (dataElement: object, event: MapMouseEvent) => void,
  onHoverOut?: (dataElement: object, event: MapMouseEvent) => void
}

type LegendConfig =
  | {
    type: 'numeric'
    colorScale: (n: number | null | undefined) => string
    domain?: [number, number]
    ticks?: Record<number, number | string>
  }
  | {
    type: 'swatches'
    swatches: {
      color: string
      label: string
      group?: string
    }[]
  }
  | {
    type: 'icons'
    icons: {
      url: string
      label: string
      group?: string
    }[]
  }

tooltip - optional - is taking the newly hovered data element as argument and should return the content of the tooltip to render. It is called once when the pointer starts to hover a data element. Built-in tooltips support string and "HTML as string" values.
- For string values, newlines are supported by using multi-line template literals.
- For HTML values, both HTML and CSS are supported, the value will be sanitized to prevent XSS attacks.
- If you need complete control over the tooltip content (e.g. for a React component), check the tooltips example.
tooltipTemplate - optional - is a fully featured template string used to generate the tooltip content based on the data for the hovered element.
- It is powered by Handlebars and you may refer to the full templating documentation here.
- It supports HTML, nested fields access, conditionals, loops, and more.
- A custom helper lets you use fallback default values: {{fallback [my field] 'default value'}}.
- Without this helper, we use '-' as a default value for all fields.
tooltipContainerStyle - optional - lets you override the style of the tooltip container with inline CSS.
persistentTooltip - optional - set this to true to turn tooltips into small cards that are all visible at once instead of on hover. Persistent tooltips are automatically positioned on the center of the data element they're attached to (limitation: elevation of the element is not accounted for at the moment). Default value: false
legend - optional - lets you configure a legend to be rendered automatically in a collapsible overlay on the viewer. The legend can be positioned using legendPosition in viewer options.
- For numeric legends, refer to options in the legend section.
- For swatches legends, refer to options in the legend section.
- For icons legends, refer to options in the legend section.
onClick - optional - is taking the data element that was clicked as argument, as well as the Mapbox mouse event that triggered the click. It is called each time a click or tap event happens.
onHover - optional - is taking the newly hovered data element as argument, as well as the Mapbox mouse event that triggered the click. The handler is called once when the pointer starts to hover a data element.
onHoverOut - optional - is taking the previously hovered data element as argument, as well as the Mapbox mouse event that triggered the click. The handler is called once when the pointer stops hovering a data element.

You may use the onClick, onHover and onHoverOut handlers to build custom behaviours in your app that respond to interactions happening in the floor plan.

Shared methods

Get a data element position on screen

This method lets you get the screen position of a data element. This can be useful to implement custom tooltips that you have full programmatic control over.

map.getDataElementPositionOnScreen(layerId: string, elementId: string) => ({
  screenX: number
  screenY: number
}) | null

layerId is the id field in your layer's definition
elementId corresponds to the id field used in the data array of your layer

If an element is found matching layerId and elementId, the function returns its coordinates when projected on screen. When no element is found, the function returns null.

Take good note:

The elevation of the element is not accounted for at the moment, due to limitations in the Mapbox APIs.
screenX and screenY are not bounded by the viewer itself, so you could have negative values, or values greater that the size of the viewer if the element is present in the 3D scene, but located outside of the current view.

Remove a layer

Removing a data layer completely is done as follow.

map.removeDataLayer(id: string) => void

id is the identifier of the layer to remove.

Remove all layers

Removing all data layers at once is done as follow.

map.removeAllDataLayers() => void

Types of layers​

Point layer​

Polygon layer​

Shared definition options​

Shared methods​

Get a data element position on screen​

Remove a layer​

Remove all layers​