InitOptions Reference

InitOptions is the single configuration object passed to init(). It combines iframe bootstrap settings, map behaviour options, and lifecycle callbacks.

import * as maps from '@mapsted/maps-js-api';
const instance = await maps.init(options: InitOptions);

---

CDN vs npm mode

The API can be loaded two ways, and a few fields are required only in npm mode.

Field	CDN mode	npm mode
mapsDomain	Injected by the script tag URL	Optional — defaults to https://maps.mapsted.com
propertyId	Injected by the script tag ?id= param	Required
accessKey	Injected by the server	Optional — overrides the Hub key
element	Optional	Optional

CDN example:

<!-- propertyId (603) and mapsDomain are encoded in the script URL -->
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=603"></script>
<script>
  mapsted.maps.init({ element: '#map' });
</script>

npm example:

import * as maps from '@mapsted/maps-js-api';
await maps.init({
  element: '#map',
  mapsDomain: 'https://maps.mapsted.com',
  propertyId: 603,
});

---

All fields

Container

Field	Type	Default	Description
element	HTMLElement | string	Full-page overlay	The map container. Pass an HTMLElement reference or a CSS selector string (e.g. "#map"). Omitting this field creates a full-viewport overlay. Throws MAPSTED-1020 if a string selector matches nothing.

---

Callbacks

Field	Type	Default	Description
onload	() => void	—	Called once when the map has fully loaded and is ready to accept commands. Equivalent to listening for the load event.

---

Authentication and domain

Field	Type	Required	Description
accessKey	string	CDN: No. npm: No (served from Hub)	Access key generated in the Mapsted Hub for your property. Throws MAPSTED-1200 / MAPSTED-1201 for invalid or expired keys.
mapsDomain	string	npm: Optional	Full URL of the maps backend host, e.g. "https://maps.mapsted.com". Defaults to https://maps.mapsted.com when omitted; set it only for a white-label or self-hosted map backend served from your own domain. Throws MAPSTED-1011 for malformed values.
propertyId	string | number	npm: Yes	The numeric property ID from the Mapsted Hub. Throws MAPSTED-1010 when mapsDomain is set but propertyId is omitted.

---

Display

Field	Type	Default	Description
language	string	undefined (iframe applies its own default: "en")	BCP 47 language tag for the initial map display language (e.g. "fr", "zh-Hans"). Can be changed at runtime with setLanguage().
loader	"cube" | "rolling" | "spinner"	undefined (iframe applies its own default: "spinner")	Loading animation style displayed while the map initialises. Setting this after init() has no effect.
focus	"property" | number | null | undefined	Building-level default	Initial focus scope. Pass "property" to start at the property (campus) level, or a buildingId number to open a specific building directly. Omit or pass undefined for the iframe default (building-level).

---

Entity and coordinate data

Field	Type	Default	Description
entityData	MapEntity[]	[]	Initial entity display overrides (name, HTML popup, custom marker). Equivalent to calling setEntityData() immediately after init().
entityDefaults	MapEntity	—	Default display properties applied to all entities without an explicit override. Equivalent to calling setEntityDefaults().
coordsData	CoordsData[]	[]	Custom coordinate markers placed at arbitrary WGS84 positions. Equivalent to calling setCoordsData().

---

Feature flags

Field	Type	Default	Description
features	Partial<FeatureFlagSet>	FULL preset	Initial UI feature flags. Merged on top of the FULL preset — only the keys you supply are changed. See Feature Flags reference.

// Disable search bar and QR code at init time
await maps.init({
  propertyId: 603,
  features: { headerBar: false, qrCode: false },
});

---

Routing and wayfinding

Field	Type	Default	Description
boost	Boost	—	Initial routing or entity-selection boost applied as soon as the map loads. See Types reference.
defaultCustomRoutingConfig	DefaultCustomRoutingConfig	All transition types enabled	Default routing preferences (elevator, escalator, stairs, ramp, indoor/outdoor). Equivalent to calling setDefaultRoutingConfig().

await maps.init({
  propertyId: 603,
  defaultCustomRoutingConfig: {
    accessibility: false,
    OptimizeItinerary: true,
    IncludeElevators: true,
    IncludeEscalators: false,
    IncludeStairs: true,
    IncludeRamps: true,
    PreferIndoorRoute: true,
    PreferOutdoorRoute: false,
  },
});

---

Overlays

Field	Type	Default	Description
mapOverlayMarkers	MapOverlayMarker[]	[]	Initial overlay markers. Equivalent to calling setMapOverlayMarkers() after load.

---

Sharing

Field	Type	Default	Description
shareUrl	string	undefined (Mapsted default URL applied by the iframe; getShareUrl() returns null when unset)	Base URL used when generating deep-link share URLs for entities and routes. The API appends /map/select?property=...&building=...&floor=...&entity=... to this base.

// Share links will be https://yourapp.com/deeplink/map/select?...
await maps.init({
  propertyId: 603,
  shareUrl: 'https://yourapp.com/deeplink',
});

---

Idle detection

Field	Type	Default	Description
idleTime	number	Disabled	Inactivity timeout in milliseconds. When no user interaction occurs for this duration, an idleChange event fires with { isUserActive: false }. Must be a positive integer. Equivalent to calling setIdleTime().

await maps.init({
  propertyId: 603,
  idleTime: 30_000, // fire idleChange after 30 s of inactivity
});

---

Advanced

Field	Type	Default	Description
strict	boolean	false	When true, deprecated V2/V3 shims throw MAPSTED-1093 instead of console.warn. Recommended for migration testing.
security	Partial<SecurityConfig>	—	Origin-allowlist and MAPSTED-1303 strict-mode validation. When provided, the API validates incoming postMessage origins against the allowlist and throws MAPSTED-1303 on mismatch instead of silently accepting. See SecurityConfig.

---

Full example

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

const instance = await maps.init({
  // Container
  element: '#map',

  // Auth
  mapsDomain: 'https://maps.mapsted.com',
  propertyId: 603,

  // Display
  language: 'en',
  loader: 'spinner',
  focus: 'property',

  // Features
  features: { qrCode: false, themeSwitcher: false },

  // Routing
  defaultCustomRoutingConfig: {
    accessibility: false,
    OptimizeItinerary: true,
    IncludeElevators: true,
    IncludeEscalators: true,
    IncludeStairs: true,
    IncludeRamps: true,
    PreferIndoorRoute: true,
    PreferOutdoorRoute: false,
  },

  // Idle
  idleTime: 60_000,

  // Ready callback
  onload: () => console.log('Map ready'),
});

---

Related pages

• Complete API Reference
• Feature Flags reference
• Type Definitions
• Error Codes