Interface: MapVXMap
Map
easeToCoordinates()
easeToCoordinates(coordinates, options?): void;Like fitCoordinates, but performs the camera change with easeTo over an
ORIENTED bounding box aligned to the target bearing.
Unlike fitCoordinates (which delegates to maplibre’s fitBounds on a north-up rectangle), this
fits the rotated extent of the coordinates, so diagonal geometries under a bearing are framed
tightly with no wasted viewport. When the camera is tilted (pitch > 0) the zoom is refined against
maplibre’s real perspective projection.
Because the resulting frame is tighter, callers must ensure their padding leaves room for any overlaid UI elements.
Accepts the same arguments as fitCoordinates; only the camera-change strategy differs.
Parameters
coordinates
LatLng[]
List of LatLng coordinates the map will ease to fit
options?
Same options as fitCoordinates
Returns
void
Example
map.easeToCoordinates(routeCoordinates, {
bearing: 140,
padding: { top: 40, right: 40, bottom: 200, left: 40 },
duration: 800,
})setBearing()
setBearing(degrees, options?): void;Sets the map bearing (rotation) in degrees, measured clockwise from north. A bearing of 0 keeps
north up, 90 puts east up, and so on.
Useful to align the map with a fixed installation (e.g. a totem/kiosk) at runtime — for instance after the visitor picks which totem they are standing at. Works even when user rotation is disabled via MapConfig.rotateEnabled or MapVXMap.setRotationEnabled, since this is a programmatic change.
Parameters
degrees
number
Target bearing in degrees. Non-finite values are ignored.
options?
Optional behavior:
animate: whentrue, the camera eases to the new bearing instead of snapping to it. Defaults tofalse.onComplete: callback invoked once the rotation has been applied (after the animation whenanimateistrue).
animate?
boolean
onComplete?
() => void
Returns
void
Example
// Snap the map so the selected totem faces up
map.setBearing(135)
// Animate the rotation and run a callback when it settles
map.setBearing(135, { animate: true, onComplete: () => console.log("aligned") })setPanEnabled()
setPanEnabled(enabled): void;Enables or disables panning the map by dragging or swiping at runtime. Runtime equivalent of MapConfig.dragPan. Combine with MapVXMap.setRotationEnabled to build a static screen where only zoom in/out is allowed.
Parameters
enabled
boolean
true to allow panning, false to lock the map position.
Returns
void
setRotationEnabled()
setRotationEnabled(enabled): void;Enables or disables user rotation of the map at runtime.
When disabled, drag-to-rotate, two-finger touch rotation and pitch-with-rotate are turned off while pinch-to-zoom keeps working. This is the runtime equivalent of MapConfig.rotateEnabled and is ideal for fixed installations that must stay locked to a configured MapConfig.bearing.
Parameters
enabled
boolean
true to allow rotation, false to lock it.
Returns
void
Example
// Lock the map to its current orientation
map.setRotationEnabled(false)setScrollZoomEnabled()
setScrollZoomEnabled(enabled): void;Enables or disables zooming with the scroll wheel / trackpad at runtime. Runtime equivalent of MapConfig.scrollZoom. Zoom buttons and pinch-to-zoom are unaffected.
Parameters
enabled
boolean
true to allow scroll-wheel zoom, false to disable it.
Returns
void
Routes
fitRouteByPlace()
fitRouteByPlace(
route,
placeId,
options?): void;Adjusts the map view to show only the steps within a specific place/building. This method filters route steps that belong to the specified place (either starting or ending inside it) and fits the map bounds to display those steps. This is particularly useful for indoor navigation where routes may cross multiple buildings or floors, allowing the map to focus on the current location.
Parameters
route
The complete route containing all steps
placeId
string
The ID of the place/building to filter steps by
options?
Optional fit options including padding, maxZoom, etc. If not provided, uses default padding values.
Returns
void
Example
const route = await map.addRoute(config)
map.fitRouteByPlace(route, "building-123", {
padding: { top: 150, right: 150, bottom: 150, left: 150 },
})Methods
addBorderToPlaces()
addBorderToPlaces(
placeIds,
color?,
width?): void;Add a border to the specific places on the map.
It only function with the internal ids from MapVX and not the clients ids.
If you only have a client id and need to use this function, you can obtain the corresponding mapvx
id from the place data using the SDK function getPlaceDetail for example.
The color and width optional arguments only function when both are sent. You should use them
with caution, because all future call will have that as the base style.
Parameters
placeIds
string[]
An array of strings representing the MapVX IDs of the places that need to have a border on the map.
color?
string
The color to use for the border instead of the current color defined in the style.
width?
number
The width for the borders instead of the current color defined in the style.
Returns
void
addCircle()
addCircle(circle): string;Adds a metric radius circle to the map and to the list of current circle references. The radius is
expressed in meters, so the circle keeps its geographic size at every zoom level. If a circle with
the same id already exists it is replaced. Circles survive style and floor changes; a circle with a
floorId is shown only while that floor is displayed.
Parameters
circle
Specifications for circle creation.
Returns
string
The added circle id.
Throws
If radiusMeters is non-positive or non-finite, or coordinates are out of bounds.
Example
const circleId = map.addCircle({
coordinate: { lat: 40.7128, lng: -74.006 },
radiusMeters: 150,
fillColor: "#FF0000",
fillOpacity: 0.2,
})addLiveRoute()
addLiveRoute(config, drawConfig?): Promise<MVXRoute>;Adds a new live route to the map or replaces the old one, using the live routing endpoint
(/sdk/liveroute). Parallel to addRoute; the live service is always fetched fresh
(never served from cache).
Safe to call repeatedly (e.g. on a timer while the user moves): each call replaces the previously drawn live route, and overlapping calls resolve to the most recent one — if a newer refresh supersedes this call while its fetch is in flight, the newer route stays on the map and this call’s result is returned without being drawn. Routes drawn with addRoute are never affected.
Parameters
config
The parameters to get and draw a route.
drawConfig?
The drawing options for the route.
Returns
Promise<MVXRoute>
The fetched route (the one drawn, unless superseded by a newer refresh).
addMarker()
addMarker(marker): string;Adding a marker to the map and to the list of current marker references.
Parameters
marker
specifications for marker creation.
Returns
string
returns the added marker id.
addRoute()
addRoute(config, drawConfig?): Promise<MVXRoute>;Adds a new route to the map or replaces the old one.
Parameters
config
drawConfig?
Returns
Promise<MVXRoute>
The route added to the map.
addStepAnimation()
addStepAnimation(
routeConfig,
drawConfig?,
animationConfig?): Promise<MVXRoute>;Add a step animation to the map.
Parameters
routeConfig
Parameters to get a route or the route object
MVXRoute | GetRouteConfiguration
drawConfig?
animationConfig?
Returns
Promise<MVXRoute>
addStepAnimationV2()
addStepAnimationV2(
routeConfig,
drawConfig?,
animationConfig?): Promise<MVXRoute>;Add a step animation to the map. Use a new endpoint for the route data.
Parameters
routeConfig
Parameters to get a route or the route object
MVXRoute | GetRouteConfiguration
drawConfig?
animationConfig?
Returns
Promise<MVXRoute>
addUserLocationTracking()
addUserLocationTracking(
enableHighAccuracy?,
geoLocation?,
icon?): void;Geolocate the user and track their current location on the current map
Parameters
enableHighAccuracy?
boolean
if true, it’ll get try to receive the best possible location results
geoLocation?
Geolocation
the geolocation object to use for tracking the user’s location. If not provided, it’ll use the default navigator.geolocation object.
icon?
HTMLElement
optional custom HTML element to use as the user location marker icon
Returns
void
centerOnCurrentStepAnimation()
centerOnCurrentStepAnimation(routeId?): void;Center the map on the current marker position for animation based on steps
Parameters
routeId?
string
Optional ID of the specific route. If not provided, uses the last added route.
Returns
void
clearBorderedPlaces()
clearBorderedPlaces(): void;Clear the borders added with addBorderToPlaces.
Returns
void
clearColoredPlaces()
clearColoredPlaces(): void;Clear the colored places on the map. This clear the places colored with setPlacesAsSelected.
Returns
void
clearTileCache()
clearTileCache(): void;Clears the tile cache, forcing tiles to be re-fetched on next request. This clears both the in-memory MapLibre cache and triggers a repaint.
Returns
void
Remarks
Useful when:
- Style has been updated on the server
- You want to free up memory
- Tiles appear corrupted or outdated
destroyMap()
destroyMap(): void;Destroy the current map
Returns
void
fitCoordinates()
fitCoordinates(coordinates, options?): void;Change the camera of the map to contain the visible area within an specific list of LatLng. If coordinates is empty, it doesn’t do anything. If it’s only one coordinate, the map center will be at that point.
The fit operation preserves the current bearing and pitch unless explicitly overridden in options.
Parameters
coordinates
LatLng[]
List of LatLng coordinates in where the map will fit
options?
Support for various options for the fit, including:
bearing: Camera bearing (rotation) in degrees. Defaults to current bearing.pitch: Camera pitch (tilt) in degrees. Defaults to current pitch.onComplete: Callback executed when the fit animation completes.
Returns
void
Example
// Fit with callback and custom bearing
map.fitCoordinates(coordinates, {
bearing: 45,
pitch: 30,
duration: 1000,
onComplete: () => console.log("Fit completed"),
})getActiveRouteIds()
getActiveRouteIds(): string[];Get the IDs of all active routes on the map.
Returns
string[]
Array of route IDs.
getBearing()
getBearing(): number;Returns the map’s current bearing. The bearing is the compass direction that is “up”; for example, a bearing of 90° orients the map so that east is up.
Returns
number
The map’s current bearing.
getCircle()
getCircle(circleId): undefined | CircleRecord;Retrieves a circle by id from the map.
Parameters
circleId
string
The id of the circle to retrieve.
Returns
undefined | CircleRecord
A defensive copy of the circle record (mutations don’t affect the map), or undefined if not found. Use the update methods to change a circle.
Example
const circle = map.getCircle(circleId)
if (circle) {
console.log(`Circle radius: ${circle.radiusMeters}m`)
}getCircles()
getCircles(): CircleRecord[];Retrieves all circles currently on the map.
Returns
A defensive copy of all circle records (mutations don’t affect the map).
Example
const circles = map.getCircles()
console.log(`Map has ${circles.length} circles`)getContainer()
getContainer(): HTMLElement;Returns the map’s containing HTML element.
Returns
HTMLElement
The map’s container.
getCurrentFloor()
getCurrentFloor(): string;Obtain the id of the current floor. If not set the parent place, return a empty string.
Returns
string
getZoomLevel()
getZoomLevel(): number;Obtain the current zoom level of the map.
Returns
number
hasCircle()
hasCircle(circleId): boolean;Checks if a circle with the given id exists on the map.
Parameters
circleId
string
The id to check.
Returns
boolean
True if a circle with that id exists, false otherwise.
Example
if (map.hasCircle(circleId)) {
map.removeCircle(circleId)
}hideCircle()
hideCircle(circleId): boolean;Hides the circle with the specified ID without deleting it. Unlike markers, a hidden circle stays hidden across floor changes and map restyles until showCircle is called.
Parameters
circleId
string
The ID of the circle to hide.
Returns
boolean
True if the circle was found and hidden, false if not found.
Example
map.hideCircle(circleId)
// Later...
map.showCircle(circleId) // Circle is now visible againhideMarker()
hideMarker(markerId): void;Hides the marker with the specified ID. This function will make the marker invisible on the map.
Parameters
markerId
string
The ID of the marker to hide.
Returns
void
isInsideBounds()
isInsideBounds(point): boolean;Check if given position is inside map bounds or not
Parameters
point
position to check
Returns
boolean
True if inside bounds or if the map doesn’t have max bounds set, False otherwise
nextStepAnimation()
nextStepAnimation(routeId?): void;Animate the current step and leave the map ready for the next step animation.
Parameters
routeId?
string
Optional ID of the specific route. If not provided, uses the last added route.
Returns
void
pauseAnimateRoute()
pauseAnimateRoute(routeId?): void;Pause of the route animation on the map.
Parameters
routeId?
string
Optional ID of the specific route to pause. If not provided, pauses the last added route.
Returns
void
Throws
A error if not exist on the map a route added by startAnimateRoute.
previousStepAnimation()
previousStepAnimation(routeId?): void;Leave the map ready to animate the previous step.
Parameters
routeId?
string
Optional ID of the specific route. If not provided, uses the last added route.
Returns
void
removeAllCircles()
removeAllCircles(): void;Removes all circles from the map.
Returns
void
removeAllMarkers()
removeAllMarkers(): void;Removes all markers from the map. This function will clear all markers currently displayed on the map.
Returns
void
removeAllRoutes()
removeAllRoutes(): void;Remove all routes from the map.
Returns
void
removeCircle()
removeCircle(circleId): void;Removes from the current map the circle that corresponds to the id provided.
Parameters
circleId
string
The id of the circle to remove.
Returns
void
removeMarker()
removeMarker(markerId): void;Removes from the current map the marker that corresponds to the id provided
Parameters
markerId
string
specifications for marker creation.
Returns
void
removeParentPlace()
removeParentPlace(): void;Removes parent place property for current map
Returns
void
removeRoute()
removeRoute(routeId?): void;Removes a route from the map. When called without arguments, removes the most recently added route (backward compatible).
Parameters
routeId?
string
Optional ID of the specific route to remove.
Returns
void
Remarks
Remove the routes added with addRoute or startAnimateRoute.
removeRouteById()
removeRouteById(routeId): void;Remove a specific route from the map by its ID.
Parameters
routeId
string
The ID of the route to remove.
Returns
void
removeUserLocationTracking()
removeUserLocationTracking(): void;Remove user location tracking from the map
Returns
void
restartAnimateRoute()
restartAnimateRoute(routeId?): void;Restart the animation of the route.
Parameters
routeId?
string
Optional ID of the specific route to restart. If not provided, restarts the last added route.
Returns
void
Throws
A error if not exist on the map a route added by startAnimateRoute.
resumeAnimateRoute()
resumeAnimateRoute(routeId?): void;Resume of the route animation on the map.
Parameters
routeId?
string
Optional ID of the specific route to resume. If not provided, resumes the last added route.
Returns
void
Throws
A error if not exist on the map a route added by startAnimateRoute.
setLang()
setLang(lang): void;function to change the lang of requests
Parameters
lang
string
request response language
Returns
void
setMaxBounds()
setMaxBounds(coordinates, options?): void;Limits the movement of the map to a bounding box calculated with the coordinate array If the coordinates are less than 2, then the function does nothing.
Parameters
coordinates
LatLng[]
List of LatLng coordinates in which the map will be limited, to these coordinates is added one kilometer of padding.
options?
Optional settings including onComplete callback
Returns
void
Example
map.setMaxBounds(coordinates, {
onComplete: () => console.log("Bounds set"),
})setMaxZoom()
setMaxZoom(zoomLvl, options?): void;Adjusts the upper zoom limit
Parameters
zoomLvl
number
The maximum zoom level
options?
Optional settings including onComplete callback
Returns
void
Example
map.setMaxZoom(18, {
onComplete: () => console.log("Max zoom set"),
})setMinZoom()
setMinZoom(zoomLvl, options?): void;Adjusts the lower zoom limit
Parameters
zoomLvl
number
The minimum zoom level
options?
Optional settings including onComplete callback
Returns
void
Example
map.setMinZoom(5, {
onComplete: () => console.log("Min zoom set"),
})setParentPlace()
setParentPlace(
place,
updateStyle,
onStyleReady?): void;Sets selected place as new parent place for loaded map and, if desired, loads new style
Parameters
place
The new parent place
updateStyle
boolean
Defines whether the new parent place’s style must be set
onStyleReady?
() => void
A callback function to be executed when the style loading is completed
Returns
void
setPlacesAsSelected()
setPlacesAsSelected(placeIds, color?): void;Colors specific places on the map based on provided place IDs.
It only function with the internal ids from MapVX and not the clients ids.
The function sets map filters to highlight given places on the displayed floor. Places previously marked as selected will lose such effect unless their id is provided in the latest call of the function. Therefore, if input array is empty, no place will be marked as selected in the map after function call.
You should use the color with caution because all future call will have that as the base color.
If you only have a client id and need to use this function, you can obtain the corresponding mapvx
id from the place data using the SDK function getPlaceDetail for example.
Parameters
placeIds
string[]
An array of strings representing the MapVX IDs of the places that need to be colored on the map.
color?
string
The color to use for the polygons instead of the current color defined in the style.
Returns
void
showCircle()
showCircle(circleId): boolean;Shows the circle with the specified ID after it has been hidden. The circle remains subject to floor visibility rules.
Parameters
circleId
string
The ID of the circle to show.
Returns
boolean
True if the circle was found and shown, false if not found.
Example
if (!map.showCircle(circleId)) {
console.error("Circle not found")
}showMarker()
showMarker(markerId): void;Shows the marker with the specified ID. This function will make the marker visible on the map.
Parameters
markerId
string
The ID of the marker to show.
Returns
void
startAnimateRoute()
startAnimateRoute(
routeConfig,
drawConfig?,
animationConfig?): Promise<MVXRoute>;Start of the route animation on the map
Parameters
routeConfig
Parameters to get a route or the route object.
MVXRoute | GetRouteConfiguration
drawConfig?
The configuration of how to draw the route on the map.
animationConfig?
Parameters for the specified animation.
Returns
Promise<MVXRoute>
The route that will be animated.
startAnimateRouteV2()
startAnimateRouteV2(
routeConfig,
drawConfig?,
animationConfig?): Promise<MVXRoute>;Start of the route animation on the map. Use a new endpoint for the route data.
Parameters
routeConfig
Parameters to get a route or the route object.
MVXRoute | GetRouteConfiguration
drawConfig?
The configuration of how to draw the route on the map.
animationConfig?
Parameters for the specified animation.
Returns
Promise<MVXRoute>
The route that will be animated.
startClickListener()
startClickListener(callback): void;Function to activate the listening to the clicks of places on the map
Parameters
callback
(arg) => void
The function that receive the id of the clicked place.
Returns
void
stopAnimateRoute()
stopAnimateRoute(): void;Complete stop of the route animation on the map
Returns
void
Deprecated
Not yet implemented.
stopClickListener()
stopClickListener(): void;Function to deactivate the listening to the clicks of places on the map
Returns
void
updateCamera()
updateCamera(newCamera, callback?): void;Update the camera position on the map
Parameters
newCamera
Options for camera update.
callback?
() => void
Function to execute after the camera updates
Returns
void
updateCircle()
updateCircle(circle): null | string;Updates an existing circle, fully replacing its configuration by id. Fields omitted from the configuration fall back to their defaults. The hidden state of the circle is preserved.
Parameters
circle
Specifications for the circle update, must include the id.
Returns
null | string
The updated circle id, or null when no circle with that id exists.
Throws
If radiusMeters is non-positive or non-finite, or coordinates are out of bounds.
Example
const result = map.updateCircle({
id: circleId,
coordinate: { lat: 40.7128, lng: -74.006 },
radiusMeters: 200,
})
if (result === null) {
console.error("Circle not found")
}updateCirclePosition()
updateCirclePosition(
circleId,
center,
radiusMeters?): boolean;Updates the center, and optionally the radius, of a circle on the map. Styling and floor assignment are left untouched. Validates all inputs.
Parameters
circleId
string
The id of the circle.
center
The new center of the circle.
radiusMeters?
number
Optional new radius in meters. If omitted, radius stays unchanged.
Returns
boolean
True if the circle was found and updated, false otherwise.
Throws
If coordinates are out of bounds or radiusMeters (if provided) is invalid.
Example
const success = map.updateCirclePosition(circleId, { lat: 40.714, lng: -74.007 }, 250)
if (!success) {
console.error("Circle not found")
}updateCircleStyle()
updateCircleStyle(circleId, style): boolean;Updates the styling of an existing circle without recreating its geometry. This is efficient when only color, opacity, or stroke properties change. Unspecified styling properties preserve their current values.
Parameters
circleId
string
The id of the circle to update.
style
Partial<CircleConfig>
Partial styling configuration (e.g., fillOpacity, strokeColor).
Returns
boolean
True if the circle was found and updated, false otherwise.
Example
map.updateCircleStyle(circleId, {
fillOpacity: 0.3,
strokeColor: "#00FF00",
})updateFloor()
updateFloor(floorId, options?): void;Updates the floor shown on the map and the reference to the current floor.
Parameters
floorId
string
floor identifier.
options?
Optional settings including onComplete callback
Returns
void
Example
map.updateFloor("floor-1", {
onComplete: () => console.log("Floor updated"),
})updateMarker()
updateMarker(marker): string;update a marker to the map and to the list of current marker references.
Parameters
marker
specifications for marker creation.
Returns
string
returns the added marker id.
updateMarkerPosition()
updateMarkerPosition(markerId, newPosition): void;Update the position of a marker on the map.
Parameters
markerId
string
The id of the marker.
newPosition
The new position of the marker.
Returns
void
updateParentPlaceAndFloor()
updateParentPlaceAndFloor(
parentPlaceId,
floorId?,
options?): void;Update the current parent place and floor displayed on the map.
Parameters
parentPlaceId
string
The id of the parent place to show.
floorId?
string
The id of the floor to show.
options?
Optional settings including onComplete callback
Returns
void
Example
map.updateParentPlaceAndFloor("parent-1", "floor-1", {
onComplete: () => console.log("Parent place and floor updated"),
})updateRouteProgress()
updateRouteProgress(
routeId,
position,
behindStyle?): void;Update the visual progress of a route based on an external user position. Splits the route into behind (already traveled) and ahead (remaining) portions at the point on the route closest to the given position.
Parameters
routeId
string
The ID of the route to update.
position
The current user position (will be projected onto the route).
behindStyle?
Optional style for the behind (traveled) portion. Defaults to gray solid.
Returns
void