Set the Initial Map View

Control the map's centre position and zoom level programmatically using setViewport().

Open in Sandbox ↗

setViewport accepts a ViewportOptions object with two optional fields — supply at least one:

Field	Type	Constraint
zoomLevel	number	10 – 24 (inclusive)
mapCenter	[number, number]	[lng, lat] in WGS84; lng ∈ [-180, 180], lat ∈ [-90, 90]

Passing neither field throws MAPSTED-1043.

Set Zoom Level

CDN

<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });
  await mapsted.maps.setViewport({ zoomLevel: 18 });
</script>

npm

import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
});
await maps.setViewport({ zoomLevel: 18 });

Valid zoom levels are 10 – 24. Values outside this range throw MAPSTED-1043

Set Map Centre

CDN

<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });
  await mapsted.maps.setViewport({
    mapCenter: [-83.0617, 42.3048], // [longitude, latitude]
  });
</script>

npm

import * as maps from '@mapsted/maps-js-api';

await maps.init({ element: '#map', propertyId: 1234 });
await maps.setViewport({
  mapCenter: [-83.0617, 42.3048], // [longitude, latitude]
});

Coordinates must be valid WGS84. Out-of-range values throw MAPSTED-1043

Set Both Simultaneously

CDN

<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });
  await mapsted.maps.setViewport({
    zoomLevel: 20,
    mapCenter: [-83.0617, 42.3048],
  });
</script>

npm

import * as maps from '@mapsted/maps-js-api';

await maps.init({ element: '#map', propertyId: 1234 });
await maps.setViewport({
  zoomLevel: 20,
  mapCenter: [-83.0617, 42.3048],
});

Listen for Changes

The API fires typed events when the zoom level or map centre changes. Use on() (the canonical event API) to subscribe:

// CDN
mapsted.maps.on('zoomLevelChange', ({ zoomLevel }) => {
  console.log('Zoom changed to:', zoomLevel);
});

mapsted.maps.on('mapCenterChange', ({ mapCenter }) => {
  console.log('Centre moved to:', mapCenter);
});

// npm
import * as maps from '@mapsted/maps-js-api';

maps.on('zoomLevelChange', ({ zoomLevel }) => {
  console.log('Zoom changed to:', zoomLevel);
});

maps.on('mapCenterChange', ({ mapCenter }) => {
  console.log('Centre moved to:', mapCenter);
});

Both events are part of KNOWN_EVENTS, with payload shapes defined in KnownEventPayload.

Note: addEventListener('zoomLevelChange', …) is a V2/V3 compatibility shim that emits a deprecation warning. Prefer on() for new code.

Querying the Current Viewport State

Call getState() to read the current zoom and centre without waiting for an event:

// CDN
const state = await mapsted.maps.getState();
console.log(state.zoomLevel);  // number | null
console.log(state.mapCenter);  // [number, number] | null

// npm
import * as maps from '@mapsted/maps-js-api';

const state = await maps.getState();
console.log(state.zoomLevel);
console.log(state.mapCenter);

getState() returns a MapState snapshot. The zoomLevel and mapCenter fields are null until the map is fully loaded.

Migration note (V2 / V3)

setMapView() was the V3 name. It is still exported from the migration shim and delegates to setViewport() with a deprecation warning. Update call sites to use setViewport() directly.

Strict mode throws MAPSTED-1093

If your app passes strict: true to init() (or calls setStrictMode(true)), calling setMapView() throws MAPSTED-1093 (ERR_METHOD_REMOVED) immediately instead of emitting a console.warn. This applies to all V3-era deprecated aliases.

Related

• API reference — full list of public methods.
• Events reference — all KNOWN_EVENTS and payload shapes.
• API lifecycle — when setViewport() can be called (after init() resolves; throws if called before the map is ready).
• Multi-building / floor navigation — companion how-to for navigateToFloorById() / navigateToFloorByName() / navigateToBuilding().
• Overlay markers — centerOnMapOverlay() for overlay-based centering.