Mapvx Web Components

A collection of interactive map components built with Lit and TypeScript.

Full documentation: docs.mapvx.app/web-components

Features

• Interactive map visualization
• Floor navigation
• Route generation
• Accessibility support
• QR mode

Installation

NPM

npm install @mapvx/web-components

CDN (iife)

https://unpkg.com/@mapvx/[email protected]/dist/iife/<component>

Always pin the version in the URL, as the snippets in this README do (never @latest, never without a version). Without one, unpkg serves the latest release: a new release changes what your page loads without you touching anything, and a CSS or layout change can break the embed or make a local patch obsolete. With the version pinned, you upgrade when you decide to, after testing it. The snippets here always point at the latest stable release: the release process rewrites them.

Service Worker (tile/asset cache)

The components automatically register a Service Worker at /mvx-tiles-sw.js when the site serves one at its root (HTTPS), and send INITIAL_TILE_LOAD with api-key and parent-place-id for a bounded, progressive tile prefetch.

• Ready to copy (same version as the components you load): https://unpkg.com/@mapvx/[email protected]/dist/sw/mvx-tiles-sw.js
• Strategies: MapVX APIs cached per endpoint; PBF tiles CacheFirst (24h, up to 10k entries); other assets StaleWhileRevalidate (*.mapvx.com, *.lazarillo.app).
• Important: serve /mvx-tiles-sw.js with Cache-Control: no-cache (avoid a long max-age on CDN/S3) and invalidate the path after every deploy.

Exported helpers (registerMvxTileServiceWorker, triggerInitialTileLoad, etc.) and the full guide (Drupal, Nginx, SW messages): docs/content/en/examples.mdx / docs/content/es/examples.mdx.

Build Structure

dist/
├── es/ # Build for ES modules
│ ├── index.js
│ ├── map-view-with-modal.js
│ ├── route-view-totems.js
│ └── assets/
├── cjs/ # Build for CommonJS
│ ├── index.cjs
│ ├── map-view-with-modal.cjs
│ └── route-view-totems.cjs
├── iife/ # Build for IIFE
│ ├── route-view-totems.js
│ └── map-view-with-modal.js
└── sw/
   └── mvx-tiles-sw.js

The build directory structure is organized as follows:

• dist/es/: Contains the ES (ECMAScript) modules build. Includes the main components and an assets/ folder with required resources.

• dist/cjs/: Contains the CommonJS build, which allows using the components in Node.js environments.

• dist/iife/: Contains the IIFE (Immediately Invoked Function Expression) build, which encapsulates all code in a self-executing function to avoid polluting the global scope.

• dist/sw/: Contains the Service Worker file that you can copy to your site's root.

Available Components

route-view-totems

A totem view for routes with QR code and animated route generation option. Includes origin and destination markers.

map-view-with-modal

A map view that only shows the destination marker.

Destination pin style

Both components accept marker-variant="full" | "compact" (default compact). The default pin is icon-only, without the place name and category; pass marker-variant="full" to get the logo + name + category bubble instead. See the Destination Pin docs.

Usage

CJS (Recommended)

// Import components
const { RouteViewTotems, MapViewWithModal } = require('@mapvx/web-components');

// Use in your HTML
<route-view-totems
  apiKey="your-api-key"
  parentPlaceId="your-venue-id"
  destinationId="your-destination-id"
  ...
></route-view-totems>

<map-view-with-modal
  apiKey="your-api-key"
  parentPlaceId="your-venue-id"
  ...
></map-view-with-modal>

IIFE (CDN)

route-view-totems

<!-- Add the script -->
<script src="https://unpkg.com/@mapvx/[email protected]/dist/iife/route-view-totems.js"></script>

<!-- Use the components -->
<route-view-totems
  apiKey="your-api-key"
  parentPlaceId="your-venue-id"
  destinationId="your-destination-id"
  ...
></route-view-totems>

map-view-with-modal

<script src="https://unpkg.com/@mapvx/[email protected]/dist/iife/map-view-with-modal.js"></script>

<map-view-with-modal
  apiKey="your-api-key"
  parentPlaceId="your-venue-id"
  placeId="your-place-id"
  ...
></map-view-with-modal>

License

This project is under Private License - only clients of Mapvx can use it.