Skip to Content
Introduction

Introduction

<mapvx-website> adds a MapVX places directory with an indoor map to any website. Visitors browse and search the places of an institution (a city, or a mall or hub within it), open a place’s details and get walking directions on the map, without leaving your page.

It is a standard custom element, so it works with plain HTML and with any framework (React, Vue, Angular, Next.js, Nuxt, SvelteKit…). It is published on npm as @mapvx/web-components-ssr. This documentation describes version 1.6.1, the current release.

Quick start

<link
  rel="stylesheet"
  href="https://unpkg.com/@mapvx/web-components-ssr@1.6.1/dist/browser/styles.css"
/>
<script
  type="module"
  src="https://unpkg.com/@mapvx/web-components-ssr@1.6.1/dist/browser/main.js"
></script>
 
<style>
  mapvx-website {
    display: block;
    width: 100%;
  }
</style>
 
<mapvx-website api-key="YOUR_API_KEY" institution-id="YOUR_INSTITUTION_ID"></mapvx-website>

Replace YOUR_API_KEY and YOUR_INSTITUTION_ID with the values MapVX gave you, and pin the exact version you tested. Installation covers npm, self-hosting and each framework.

type="module" and styles.css are both required: main.js is an ES module, and the stylesheet carries the color and font settings, the map styles and the icon styles.

What it includes

  • Directory: a paginated grid of place cards with category tabs, search and, when there is more than one city, a city filter. Visitors switch between the grid and a map view.
  • Place profile: image, category, today’s hours with the weekly schedule, deals and events, description, address, phone numbers and website.
  • Indoor map: markers for the listed places, a floor selector inside buildings with more than one floor, a compass that shows the map’s rotation, and zoom, re-center and current-location controls.
  • Directions: walking routes between two places, or from the visitor’s current location, with step-by-step guidance and the floors the route passes through. The place profile also links to driving directions in Google Maps.
  • Routing from a dropped pin: a button on the map lets a visitor drop a pin anywhere and drag it, and the route then starts from that point instead of from a listed place. The pin can be dropped before the destination is chosen, or after.
  • Integration hooks: a userAction event when visitors pick a category, search, open a place, ask for directions or return to the home screen, the legacy cardSelected event for card clicks, and deep links through query parameters.

How it works

  • The element is an Angular application packaged as a custom element. You load one ES module (main.js) and one global stylesheet (styles.css). Angular and the maps SDK are bundled inside main.js, so your page needs no other library; main.js loads its chunk-*.js files from its own folder when it needs them.
  • It renders in the page’s regular DOM, not in a Shadow DOM: its own styles are scoped, but your page’s CSS can reach inside it. See Style isolation.
  • It renders only in the browser. Server-rendered sites can prepare the initial-data attribute on the server; see SSR and initial data.
  • Loading main.js also loads Google Analytics for MapVX, and the bundled maps SDK reports its errors to MapVX. See Security and privacy.
  • The interface is in English.
  • Use a single <mapvx-website> per page: several elements share one application (router, loaded data, map and SDK) and interfere with each other. See Multiple instances.

Requirements

  • An API key and an institution id issued by MapVX.
  • A browser with custom elements, ES modules and CSS container queries. The map needs WebGL; plan for WebGL2 (see Installation).
  • If your site sends a Content Security Policy, allow the sources listed in Security and privacy.

Packages

PackageUse
@mapvx/web-components-ssrThe <mapvx-website> element and its TypeScript types.
@mapvx/web-components-ssr-helpersServer-side helper that prepares the initial-data attribute.

Next steps

Last updated on
Installation