Embed a map on your website

Load embed.js and add a <metamaps-embed> element to display a published Metamaps map on an existing website. You do not need an API key or an npm package.

Add your first map

Publish your map in the admin console and find its slug at the end of the public URL. Replace example below with that slug, then place the element where you want the map to appear.

<script src="https://cdn.metamaps.jp/sdk/js/embed.js" defer></script>

<metamaps-embed
  slug="example"
  title="Facility map"
></metamaps-embed>

Load the script once per page. Use a published map; do not pass an admin console URL as src.

Set the height and layout

The element fills the width of its container. Set its height with the --metamap-embed-height CSS custom property.

<style>
  .facility-map {
    --metamap-embed-height: 600px;
  }
  @media (max-width: 600px) {
    .facility-map {
      --metamap-embed-height: 70svh;
    }
  }
</style>

<metamaps-embed
  class="facility-map"
  slug="example"
  title="Facility map"
></metamaps-embed>

The default height is min(72svh, 720px), or 68svh at viewport widths of 520px or less. Browsers without svh support use vh. The minimum height is 360px, or 420px at widths of 520px or less. To make the element shorter, set its min-height as well.

Set the initial view with a URL

To select a floor, spot, or language, use a public URL created in the admin console as src. If both src and slug are present, src takes precedence.

<metamaps-embed
  src="https://metamaps.jp/d/example?floor=2F&amp;lang=en"
  title="Second-floor map"
></metamaps-embed>

Use an HTTPS URL for src. For local development, http://localhost and http://127.0.0.1 are also accepted. The script adds embed and embedOrigin automatically. The floor value is the floor label registered in the admin console.

Element attributes

Attribute	Value	Purpose
`slug`	3–60 lowercase letters, digits, and hyphens	The map to display; required when `src` is absent
`src`	An HTTPS public map URL	Use query parameters or a POI display set URL
`title`	A descriptive name for the map	The accessible name of the internal iframe
`loading`	`lazy` or `eager`	Defaults to lazy loading; use `eager` to load earlier
`edge-gutter`	A number from 0 to 80	Width of the page-scrolling area on each side, in pixels; defaults to 20

Map interaction and page scrolling

Initially, scrolling over the map scrolls the page. Click or tap the map to enable map interaction. Using either edge area, interacting outside the map, scrolling the page, or pressing Escape returns the element to page-scrolling mode.

On a desktop, a sustained fast wheel gesture during map interaction switches to scrolling the parent page. On a phone, swipe in the center to interact with the map and swipe along either edge to scroll the page.

Events and input errors

Listen for metamap-interactionchange to observe interaction changes. Its detail.mode is map or page. Invalid slugs or URLs emit metamap-embederror and leave the map unloaded.

To receive events from initialization, register listeners before the custom element is upgraded. Place the following script after the embed element. The deferred embed.js runs after HTML parsing.

<script>
  const map = document.querySelector('metamaps-embed');
  map.addEventListener('metamap-interactionchange', (event) => {
    console.log(event.detail.mode);
  });
  map.addEventListener('metamap-embederror', (event) => {
    console.error(event.detail.error.message);
  });
</script>

metamap-embederror reports invalid element inputs. It does not report network failures or whether the map is published.

Troubleshooting

Open the public map URL directly to check that it works. Confirm the map is published and that you have replaced example.
Check that your CMS preserves both the script tag and the custom element.
If your website has a Content Security Policy, allow https://cdn.metamaps.jp in script-src and https://metamaps.jp in frame-src. Move the CSS and event examples into external files if your site's policy requires it.
If your website sends a Permissions-Policy header that limits geolocation, include https://metamaps.jp. Otherwise the map's location button cannot read the device location.
To update map data from your system, see the API guide. To display a map in a mobile app, see the SDK guides.