Interface: MapConfig

Basic configuration for the map. Provides essential settings for initializing and customizing map behavior.

Example

const mapConfig: MapConfig = {
  zoom: 15,
  center: { lat: 40.7128, lng: -74.006 },
  parentPlaceId: "building-1",
  onMapReady: () => console.log("Map is ready!"),
  enableHover: true,
  showCompass: true,
}

Properties

authToken?

optional authToken?: string;

(Optional) Authentication token for accessing protected map resources. Required for loading map related data from Portal.

bearing?

optional bearing?: number;

(Optional) Initial bearing (rotation) of the map in degrees, clockwise from north.

bearingSnap?

optional bearingSnap?: number;

(Optional) The bearing snap threshold in degrees.

center

center: LatLng

The initial center coordinates of the map.

doubleClickZoom?

optional doubleClickZoom?: boolean;

(Optional) Whether double-click/double-tap zooms the map.

dragPan?

optional dragPan?: boolean;

(Optional) Whether the user can pan by dragging/swiping.

enableHover?

optional enableHover?: boolean;

(Optional) Whether to enable hover interactions on the map.

fadeDuration?

optional fadeDuration?: number;

Duration in milliseconds of the label/symbol fade-in and cross-fade between tiles. Mirrors MapLibre’s fadeDuration.

Every fade keeps the map re-rendering for its whole duration after a gesture ends, so a shorter one lets a low-end GPU go idle sooner — but do not reach for 0. MapLibre’s Style._updatePlacement treats 0 as forceFullPlacement, which replaces incremental, pauseable symbol placement with a full pass, and on a low-end device that costs more than the fade it saves. Measured on an RK3566 totem panel, 600 was the better setting. Lengthen or shorten it; leave 0 alone.

Default Value

300

Example

// Longer fades, fewer full symbol-placement passes on a low-end panel.
const mapConfig: MapConfig = { zoom: 19, center, fadeDuration: 600 }

institutionId?

optional institutionId?: string;

(Optional) The institution identifier for map context. Required for loading map related data from Portal.

interactive?

optional interactive?: boolean;

(Optional) Master switch for all user interaction (pan/zoom/rotate).

keyboard?

optional keyboard?: boolean;

(Optional) Whether keyboard shortcuts can pan/zoom/rotate the map.

lang?

optional lang?: string;

(Optional) Language code for map labels and UI.

markerLayout?

optional markerLayout?: MarkerLayoutConfig;

(Optional) Automatic marker label collision avoidance configuration.

maxBounds?

optional maxBounds?: LatLng[];

(Optional) Array of coordinates defining the maximum bounds of the map.

maxZoom?

optional maxZoom?: number;

(Optional) Maximum allowed zoom level.

minZoom?

optional minZoom?: number;

(Optional) Minimum allowed zoom level.

mode?

optional mode?: "2D" | "3D";

Mode of the map. Controls the mode of the map.

This is currently a experimental feature.

Don’t use it unless you know what you are doing.

When set to "3D", deck.gl / GLB scene features run only if MapConfig.scene3D is not explicitly disabled (scene3D.enabled !== false). Omitting scene3D keeps previous behavior.

Default

"2D"

navigationPosition?

optional navigationPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";

(Optional) Position of the navigation controls on the map.

onFloorChange?

optional onFloorChange?: (newFloorId) => void;

(Optional) Callback invoked when the floor changes. Receives the new floor ID.

Parameters

newFloorId

string

Returns

void

onMapReady?

optional onMapReady?: () => void;

(Optional) Callback invoked when the map is ready.

Returns

void

onParentPlaceChange?

optional onParentPlaceChange?: (newParentPlaceId) => void;

(Optional) Callback invoked when the parent place changes. Receives the new parent place ID.

Parameters

newParentPlaceId

string

Returns

void

onRotate?

optional onRotate?: (degrees) => void;

(Optional) Callback invoked when the map is rotated. Receives the rotation in degrees.

Parameters

degrees

number

Returns

void

onScene3DModelsProgress?

optional onScene3DModelsProgress?: (progress) => void;

Callback invoked as the declarative GLB models in MapConfig.scene3D download and decode, and once more when the whole batch has settled. Fires only when MapConfig.mode is "3D" and scene3D.models declares at least one asset.

Parameters

progress

Scene3DModelsProgress

Aggregate progress across every distinct asset URL.

Returns

void

Example

const mapConfig: MapConfig = {
  mode: "3D",
  scene3D,
  onScene3DModelsProgress: (progress) => {
    updateLoadingBar(progress.loadedAssets, progress.totalAssets)
  },
}

onZoomEnd?

optional onZoomEnd?: (zoomLvl?) => void;

(Optional) Callback invoked when the zoom operation ends. Receives the new zoom level.

Parameters

zoomLvl?

number

Returns

void

otherPotentialParentPlacesIds?

optional otherPotentialParentPlacesIds?: string[];

(Optional) List of alternative parent place IDs.

parentPlaceId?

optional parentPlaceId?: string;

(Optional) The ID of the parent place to display.

pitch?

optional pitch?: number;

(Optional) The pitch (tilt) of the map in degrees.

pitchEnabled?

optional pitchEnabled?: boolean;

Whether the user can change the map pitch (tilt) with gestures.

When false, two-finger touch pitch and pitch-with-rotate are disabled and the pitch is pinned to MapConfig.pitch (or 0 when omitted) through MapLibre’s minPitch/maxPitch, so a later camera update cannot tilt the map either. A fixed installation kept at a constant tilt skips the re-rendering that pitch changes trigger, which matters on low-end GPUs.

Default Value

true

Example

// Keep the venue tilt but stop visitors from changing it
const mapConfig: MapConfig = { zoom: 19, center, pitch: 60, pitchEnabled: false }

pixelRatio?

optional pixelRatio?: number;

Pixel ratio used to size the map canvas. Mirrors MapLibre’s pixelRatio.

Values below 1 render the map at a lower internal resolution and let the GPU scale it up: a direct fill-rate reduction for low-end hardware (0.75 draws ~44% fewer pixels) at the cost of slightly softer edges. Leave unset to keep MapLibre’s default (window.devicePixelRatio).

Default Value

window.devicePixelRatio

Example

const mapConfig: MapConfig = { zoom: 19, center, pixelRatio: 0.75 }

rotateEnabled?

optional rotateEnabled?: boolean;

(Optional) Whether the user can rotate the map; keeps pinch-zoom when disabled.

scene3D?

optional scene3D?: Scene3DConfig;

Optional 3D scene configuration: GLB models and deck.gl overlay styling. When MapConfig.mode is "3D", set enabled: false to turn off 3D scene features (overlay, escalator layer, etc.) while keeping other map behavior.

See

Scene3DConfig

scrollZoom?

optional scrollZoom?: boolean;

(Optional) Whether the scroll wheel/trackpad can zoom the map.

showCompass?

optional showCompass?: boolean;

(Optional) Whether to display the compass control.

showZoom?

optional showZoom?: boolean;

(Optional) Whether to display the zoom control.

styleRef?

optional styleRef?: string;

Style variant to request for the venue (style_ref on mapStyleJson), applied to the initial load and to every later parent-place change. Use "raster" to pick the pre-rendered raster basemap of an offline bundle. Leave unset for the venue’s default style.

Default Value

the venue's default style

Example

const mapConfig: MapConfig = { zoom: 19, center, styleRef: "raster" }

styleTheme?

optional styleTheme?: string;

Style theme to request alongside MapConfig.styleRef (style_theme on mapStyleJson). Leave unset for the style’s own theme.

Default Value

the style's default theme

tileCache?

optional tileCache?: MapTileCacheConfig;

Tile cache configuration options Controls how map tiles are cached in memory and persisted

See

MapTileCacheConfig for available options

touchZoomRotate?

optional touchZoomRotate?: boolean;

(Optional) Whether pinch gestures can zoom the map on touch devices.

zoom

zoom: number

The initial zoom level of the map.