# 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.

```html
<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.

```html
<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.

```html
<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.

```html
<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](/developers/api/). To display a map in a mobile app, see the [SDK guides](/developers/sdk/).