JavaScript SDK

The JavaScript SDK gives you full programmatic control over an embedded Layota map.

Installation

npm install @layota/map-sdk

Or use the CDN (UMD):

<script src="https://unpkg.com/@layota/map-sdk"></script>
<script>
  const map = new LayotaMap.LayotaMap({ ... })
</script>

Quick Start

import { LayotaMap } from '@layota/map-sdk'

const map = new LayotaMap({
  container: '#map',
  projectId: 'your-project-id',
})

await map.ready()

map.selectArea('coffee-shop')
   .focusOn('coffee-shop')

Configuration

const map = new LayotaMap({
  container: '#map',              // Required — CSS selector or HTMLElement
  projectId: 'proj-uuid',         // Required — published project UUID
  apiKey: 'sk_...',               // Required if project has allowed domains
  theme: 'dark',                  // 'light' | 'dark' | 'blue' | 'auto'
  language: 'en',                 // Language code
  levelId: 'floor-2',             // Start on this level (id, key, or name)
  areaId: 'cafe',                 // Select this area on load (id, key, or title)
  markerId: 'exit-north',         // Select this marker on load (id, key, or title)
  baseUrl: 'https://layota.app',  // Override for self-hosted installations
})

Methods

Lifecycle

// Wait for the map to finish loading
await map.ready()

// Clean up the iframe and all event listeners
map.destroy()

Level Control

// Switch level by id, key (slug), or name
map.selectLevel('floor-2')

// Fetch all visible levels
const levels: Level[] = await map.getLevels()
// Level: { id: string, name: string }

Area & Marker Selection

// Select by id, key (slug), or title — opens the info card
map.selectArea('cafe')
map.selectArea('cafe', 'floor-1')   // specify level for disambiguation

map.selectMarker('exit-north')
map.selectMarker('exit-north', 'floor-1')

// Close the info card and deselect
map.clearSelection()

Navigation

// Pan and zoom to an area or marker — switches level if needed
map.focusOn('cafe')

// Reset zoom and pan to default
map.resetView()

// Set zoom level (scale must be > 0)
map.setZoom(1.5)

Search

// Open the search panel and filter results by query
map.search('coffee')

// Clear the search
map.search('')

Routing

const from = { id: 'entrance', type: 'area', levelId: 'floor-1' }
const to   = { id: 'cafe',     type: 'area', levelId: 'floor-2' }

// Build and display a route
map.buildRoute(from, to)

// Remove the displayed route
map.clearRoute()

Language

// Get available languages
const { languages, current } = await map.getLanguages()
// Language: { code: string, name: string }
// current: currently active language code

// Switch language at runtime
map.setLanguage('de')

Theme

// Switch map theme at runtime: 'light', 'dark', 'blue', or 'auto'
map.setTheme('dark')

Areas & Markers Data

// Get all areas across all levels
const allAreas: Area[] = await map.getAreas()

// Get areas for a specific level (by id, key, or name)
const floorAreas: Area[] = await map.getAreas('floor-1')

// Same for markers
const allMarkers: Marker[] = await map.getMarkers()
const floorMarkers: Marker[] = await map.getMarkers('floor-1')
// Area: { id, title, levelId, key }
// Marker: { id, title, levelId, key }

Project Data

const project: ProjectInfo = await map.getProject()
// ProjectInfo: { id, settings, levels: ProjectLevel[] }
// ProjectLevel: { id, name, areas: Area[], markers: Marker[] }

Method Chaining

All commands return this for chaining:

map.selectLevel('floor-1')
   .selectArea('cafe')
   .focusOn('cafe')
   .setZoom(1.5)
   .search('cafe')

Events

Subscribe

map.on('areaClick', (area) => {
  console.log('Clicked:', area.title)
})

map.on('levelChange', (level) => {
  console.log('Switched to:', level.name)
})

Subscribe Once

map.once('ready', () => {
  console.log('Map loaded')
})

Unsubscribe

const handler = (area) => console.log(area)
map.on('areaClick', handler)
map.off('areaClick', handler)

Event Reference

Event	Payload	Description
ready	—	Map fully loaded
levelChange	Level	User or SDK switched levels
areaClick	Area	User clicked an area
markerClick	Marker	User clicked a marker
areaSelect	Area	Area selected programmatically
markerSelect	Marker	Marker selected programmatically
routeBuilt	{ route: RouteResult, levelId: string }	Route calculated
routeNotFound	—	No route found
languageChange	{ language: string }	Language switched via setLanguage()
error	string	SDK error

TypeScript Types

All types are exported from the package:

import type {
  LayotaMapOptions,
  Level,
  Language,
  Area,
  Marker,
  RouteEntity,
  RoutePoint,
  RouteSegment,
  RouteResult,
  ProjectLevel,
  ProjectInfo,
  SdkEventMap,
} from '@layota/map-sdk'

Architecture

The SDK creates a hidden <iframe> pointing to https://layota.app/embed/{projectId} and communicates with it via window.postMessage. Commands sent before the map is ready are queued and flushed automatically once the READY event fires.