MapVX Web SDK

A framework-agnostic TypeScript SDK for integrating indoor navigation and mapping capabilities into web applications. Works with Angular, React, Lit, and vanilla JavaScript.

Installation

The package is available on the public npm registry. No authentication token is required.

npm install @mapvx/web-js

Then load the SDK styles using one of these methods:

import { initializeSDK, loadStyles } from "@mapvx/web-js"

// Load default styles (includes all required CSS)
loadStyles()

Or include the stylesheet manually in your HTML:

<link rel="stylesheet" href="./node_modules/@mapvx/web-js/dist/umd/styles.css" />

Module Formats

The SDK ships in three formats:

| Format | Entry Point | Use Case | | ------ | ----------- | -------- | | ESM | dist/es/index.js | Modern bundlers (Vite, webpack 5, Rollup) | | CJS | dist/cjs/index.js | Node.js, legacy bundlers | | UMD | dist/umd/index.js | <script> tags, CDNs |

Bundlers automatically pick the right format via the exports field in package.json.

Quick Start

import { initializeSDK } from "@mapvx/web-js"

// Initialize the SDK with your API token
const sdk = initializeSDK("your-api-token")

// Create a map
const container = document.getElementById("map-container")
const map = sdk.createMap(container, {
  zoom: 18,
  center: { lat: 40.7128, lng: -74.006 },
  parentPlaceId: "your-building-id",
  onMapReady: () => console.log("Map is ready!"),
})

Core Features

Fetching Places

// Get all available places for your API token
const places = await sdk.getAvailablePlaces()

// Get sub-places within a building
const subPlaces = await sdk.getSubPlaces("building-id")

// Get details for a specific place
const place = await sdk.getPlaceDetail("place-id")

// Search for places
const results = await sdk.getPlacesByInput("coffee", "institution-id", "building-id")

Navigation Routes

// Get a route between two points
const route = await sdk.getRoute({
  parentPlaceId: "building-id",
  from: { placeId: "origin-place-id" },
  to: { placeId: "destination-place-id" },
  mode: "walking",
})

// Draw a route on the map
const routeOnMap = await map.addRoute(
  {
    parentPlaceId: "building-id",
    from: { placeId: "origin-place-id" },
    to: { placeId: "destination-place-id" },
  },
  {
    width: 4,
    style: { type: "solid", color: "#007AFF" },
  }
)

// Animate a route
await map.startAnimateRoute({
  parentPlaceId: "building-id",
  from: { placeId: "origin-place-id" },
  to: { placeId: "destination-place-id" },
})

Markers

// Add a marker
const markerId = map.addMarker({
  id: "my-marker",
  position: { lat: 40.7128, lng: -74.006 },
  color: "#FF0000",
})

// Update marker position
map.updateMarkerPosition("my-marker", { lat: 40.713, lng: -74.007 })

// Remove a marker
map.removeMarker("my-marker")

User Location

// Track user location on the map
map.addUserLocationTracking(true) // true for high accuracy

// Watch user position
const watchId = sdk.watchUserPosition(
  (position) => console.log("Position:", position),
  (error) => console.error("Error:", error)
)

// Stop watching
sdk.unWatchUserPosition(watchId)

Floor Navigation

// Change the displayed floor
map.updateFloor("floor-2")

// Get current floor
const currentFloor = map.getCurrentFloor()

// Listen for floor changes
const mapConfig = {
  // ...other config
  onFloorChange: (newFloorId) => console.log("Floor changed to:", newFloorId),
}

Configuration Options

SDK Configuration

const sdk = initializeSDK("your-api-token", {
  lang: "en", // Language for labels and responses
  apiUrl: "https://public-api.mapvx.com", // API endpoint (default)
  cache: {
    persistent: true, // Enable localStorage persistence
    maxStorageBytes: 5 * 1024 * 1024, // 5MB cache limit
    configs: {
      places: { maxItems: 1000, ttlMs: 60000 },
    },
  },
})

Map Configuration

const map = sdk.createMap(container, {
  zoom: 18,
  center: { lat: 40.7128, lng: -74.006 },
  parentPlaceId: "building-id",

  // Optional settings
  minZoom: 15,
  maxZoom: 22,
  pitch: 45, // 3D tilt in degrees
  showCompass: true,
  showZoom: true,
  navigationPosition: "top-right",
  enableHover: true,
  lang: "en",

  // Tile caching for performance
  tileCache: {
    enabled: true,
    maxTiles: 500,
    ttlMs: 60 * 60 * 1000, // 1 hour
    persistToServiceWorker: true,
    preloadAdjacentZooms: false,
  },

  // Event callbacks
  onMapReady: () => {},
  onZoomEnd: (zoomLevel) => {},
  onRotate: (degrees) => {},
  onFloorChange: (floorId) => {},
  onParentPlaceChange: (placeId) => {},
})

Tile Cache Management

The SDK provides built-in tile caching for improved performance:

// Configure tile caching when creating the map
const map = sdk.createMap(container, {
  // ...other config
  tileCache: {
    enabled: true, // Enable caching (default: true)
    maxTiles: 400, // Max tiles in memory (default: 400)
    ttlMs: 30 * 60 * 1000, // Cache TTL in ms (default: 30 minutes)
    persistToServiceWorker: true, // Enable offline caching (default: true)
    preloadAdjacentZooms: false, // Preload nearby zoom levels (default: false)
  },
})

// Clear the tile cache when needed
map.clearTileCache()

Documentation

For complete documentation and examples, visit the MapVX Web SDK Docs.

API Reference

• MapVXSDK - Main SDK interface
• MapVXMap - Map instance interface
• MapConfig - Map configuration options
• MVXPlace - Place data model
• MVXRoute - Route data model

FAQ

Q: Navigation controls are missing on map generation, what can I do?

A: Ensure you have included the MapLibre GL CSS and JS files in your HTML. See the Installation section above.

Q: How do I handle multiple buildings?

A: Use the otherPotentialParentPlacesIds option in your map configuration or the otherParentPlacesIds parameter when searching for places.

Q: How do I enable offline map access?

A: Set persistToServiceWorker: true in the tileCache configuration. This enables service worker caching for offline tile access.

Support

For support, please contact your MapVX representative or visit MapVX.