Floor Management

This guide covers how to manage floors in an indoor map using the MapVX Web SDK. You will learn how to switch floors, react to floor changes, change the active building, and clean up when navigation ends.

Prerequisites

You need a MapVXMap instance before working with floors. If you have not created one yet, initialize the SDK and create a map first:


import { initializeSDK } from "@mapvx/web-js"
 
const sdk = initializeSDK("<YOUR-API-KEY>")
 
const map = sdk.createMap(mapContainer, {
  center: { lat: -33.418835, lng: -70.642388 },
  zoom: 18,
  parentPlaceId: "<YOUR-BUILDING-ID>",
})

Listening for floor changes

The most common requirement is reacting when the user or the application changes the active floor. Pass an onFloorChange callback in MapConfig when creating the map:


const map = sdk.createMap(mapContainer, {
  center: { lat: -33.418835, lng: -70.642388 },
  zoom: 18,
  parentPlaceId: "<YOUR-BUILDING-ID>",
  onFloorChange: (newFloorId: string) => {
    console.log("Active floor changed to:", newFloorId)
    // Update your UI to reflect the new floor
    updateFloorSelector(newFloorId)
  },
})

onFloorChange fires whenever the displayed floor changes, whether triggered programmatically or by user interaction.

Getting the current floor

Use getCurrentFloor to read the active floor ID at any point:


const currentFloorId = map.getCurrentFloor()
console.log("Currently showing floor:", currentFloorId)

If no parent place has been set on the map, getCurrentFloor returns an empty string.

Switching to a different floor

Use updateFloor to programmatically change the floor displayed on the map. Pass the floor ID and an optional FloorUpdateOptions object:


map.updateFloor("<FLOOR-ID>")

To run code after the floor transition completes, provide an onComplete callback:


map.updateFloor("<FLOOR-ID>", {
  onComplete: () => {
    console.log("Floor update finished, map is ready")
    // Place markers, fit bounds, or trigger other map operations here
  },
})

Building a floor selector

A typical pattern is to render a list of available floors and call updateFloor when the user picks one:


function onFloorButtonClick(floorId: string): void {
  const previousFloor = map.getCurrentFloor()
 
  if (previousFloor === floorId) {
    return // Already on this floor, nothing to do
  }
 
  map.updateFloor(floorId, {
    onComplete: () => {
      highlightActiveFloorButton(floorId)
    },
  })
}

Switching the parent place and floor together

When the user navigates to a different building, use updateParentPlaceAndFloor to change both the active building and the floor in a single call:


map.updateParentPlaceAndFloor("<NEW-BUILDING-ID>", "<FLOOR-ID>")

The floorId argument is optional. When omitted, the map switches to the new building and displays its default floor:


map.updateParentPlaceAndFloor("<NEW-BUILDING-ID>")

Use onComplete to act after the transition:


map.updateParentPlaceAndFloor("<NEW-BUILDING-ID>", "<FLOOR-ID>", {
  onComplete: () => {
    console.log("Building and floor transition complete")
  },
})

Example: following a route across buildings

When a navigation route moves the user from one building to another, updateParentPlaceAndFloor keeps the map context in sync:


function onRouteStepChange(buildingId: string, floorId: string): void {
  map.updateParentPlaceAndFloor(buildingId, floorId, {
    onComplete: () => {
      // Re-center the map on the user's current position
      map.fitCoordinates([userPosition])
    },
  })
}

Setting a new parent place from a place object

If you already have an MVXPlace object (for example, returned by sdk.getPlaceDetail), use setParentPlace to set it as the active building:


const place = await sdk.getPlaceDetail("<BUILDING-ID>")
 
// Set the parent place and load its map style
map.setParentPlace(place, true, () => {
  console.log("New building style loaded and ready")
})

The second argument, updateStyle, controls whether the map loads the new building’s tile style:

Pass true when switching to a building whose style is different from the one currently loaded.
Pass false to update the internal parent place reference without reloading the map style (useful when the style is already correct or managed separately).


// Switch building context without reloading the style
map.setParentPlace(place, false)

The onStyleReady callback fires only when updateStyle is true and the style has finished loading.

Removing the parent place

When the user leaves an indoor venue entirely, call removeParentPlace to clear the building context from the map:


map.removeParentPlace()

After this call, getCurrentFloor returns an empty string and floor-specific filters are cleared. Use this when switching back to an outdoor view or when the user exits a building.

Reacting to parent place changes

You can also listen for parent place changes via the onParentPlaceChange callback in MapConfig:


const map = sdk.createMap(mapContainer, {
  center: { lat: -33.418835, lng: -70.642388 },
  zoom: 18,
  onParentPlaceChange: (newParentPlaceId: string) => {
    if (!newParentPlaceId) {
      showOutdoorUI()
    } else {
      showIndoorUI(newParentPlaceId)
    }
  },
  onFloorChange: (newFloorId: string) => {
    updateFloorSelector(newFloorId)
  },
})

Complete example

The following shows a self-contained setup that combines initialization, floor change listening, and a floor selector:


import { initializeSDK, MapVXMap } from "@mapvx/web-js"
 
const sdk = initializeSDK("<YOUR-API-KEY>")
 
let map: MapVXMap
 
function initMap(container: HTMLElement): void {
  map = sdk.createMap(container, {
    center: { lat: -33.418835, lng: -70.642388 },
    zoom: 18,
    parentPlaceId: "<YOUR-BUILDING-ID>",
    onFloorChange: (newFloorId: string) => {
      updateFloorUI(newFloorId)
    },
    onParentPlaceChange: (newParentPlaceId: string) => {
      if (!newParentPlaceId) {
        showOutdoorView()
      }
    },
  })
}
 
function switchFloor(floorId: string): void {
  map.updateFloor(floorId, {
    onComplete: () => {
      console.log("Now showing floor:", map.getCurrentFloor())
    },
  })
}
 
function switchBuilding(buildingId: string, floorId: string): void {
  map.updateParentPlaceAndFloor(buildingId, floorId, {
    onComplete: () => {
      console.log("Building and floor ready")
    },
  })
}
 
function exitBuilding(): void {
  map.removeParentPlace()
}
 
function updateFloorUI(floorId: string): void {
  // Update your floor selector component here
}
 
function showOutdoorView(): void {
  // Switch to outdoor map view
}

API reference

MapVXMap - Full map interface including all floor methods
MapConfig - Map creation options including onFloorChange and onParentPlaceChange
FloorUpdateOptions - Options accepted by updateFloor and updateParentPlaceAndFloor
MVXPlace - Place object used with setParentPlace