arcgis-embeddable-maps

Embed lightweight, self-contained maps in web pages using the Embeddable Components package. Use for quick map embeds with minimal code and built-in UI controls.

Quality

72%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./contexts/5.0/skills/arcgis-embeddable-maps/SKILL.md

ArcGIS Embeddable Maps

Use this skill when embedding a lightweight, self-contained map into a web page with minimal code. The @arcgis/embeddable-components package provides the arcgis-embedded-map web component - a single element that bundles a WebMap viewer with optional built-in UI controls (legend, bookmarks, basemap gallery, fullscreen). This is a new component package in 5.0 with no 4.x equivalent.

When to use arcgis-embedded-map vs arcgis-map: Use arcgis-embedded-map for simple, read-only map embeds (blogs, dashboards, reports) where you don't need custom widgets, editing, or programmatic map control. Use arcgis-map (see arcgis-core-maps) for full-featured applications.

Import Patterns

CDN (No Build Tools)

<!-- Load ArcGIS Maps SDK -->
<script src="https://js.arcgis.com/5.0/"></script>
<!-- Load Embeddable Components -->
<script type="module" src="https://js.arcgis.com/5.0/embeddable-components/"></script>

Direct ESM Imports (Build Tools)

import "@arcgis/embeddable-components/components/arcgis-embedded-map";

arcgis-embedded-map Component

Properties

Property	Attribute	Type	Default	Description
`itemId`	`item-id`	`string`	-	Required. Portal item ID of a WebMap
`portalUrl`	`portal-url`	`string`	`"https://www.arcgis.com"`	Portal URL (ArcGIS Online or Enterprise)
`apiKey`	`api-key`	`string`	-	API key for accessing the resource
`center`	`center`	`number[] \| Point`	-	View center `[longitude, latitude]`
`zoom`	`zoom`	`number`	-	Zoom level
`scale`	`scale`	`string`	-	Map scale at center
`extent`	-	`Extent`	-	Visible map extent (set via JS)
`webMap`	-	`WebMap`	-	WebMap instance (set via JS, alternative to `itemId`)
`theme`	`theme`	`string`	`"light"`	Component theme: `"light"` or `"dark"`

UI Control Properties

Property	Attribute	Type	Default	Description
`headingEnabled`	`heading-enabled`	`boolean`	`false`	Show the WebMap title
`legendEnabled`	`legend-enabled`	`boolean`	`false`	Show the legend panel
`bookmarksEnabled`	`bookmarks-enabled`	`boolean`	`false`	Show bookmarks panel
`basemapGalleryEnabled`	`basemap-gallery-enabled`	`boolean`	`false`	Show basemap gallery panel
`informationEnabled`	`information-enabled`	`boolean`	`false`	Show information panel
`shareEnabled`	`share-enabled`	`boolean`	`false`	Show button to open in Map Viewer
`fullscreenDisabled`	`fullscreen-disabled`	`boolean`	`false`	Disable the fullscreen button
`scrollEnabled`	`scroll-enabled`	`boolean`	`true`	Enable mouse wheel scroll zooming
`timeZoneLabelEnabled`	`time-zone-label-enabled`	`boolean`	`false`	Show time zone labels

Methods

Method	Returns	Description
`componentOnReady()`	`Promise<void>`	Resolves when the component is fully loaded

Basic Usage

Minimal Embed

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

Embed with All UI Controls

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  heading-enabled
  legend-enabled
  bookmarks-enabled
  basemap-gallery-enabled
  information-enabled
  share-enabled
  style="width: 100%; height: 500px;">
</arcgis-embedded-map>

Dark Theme

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  theme="dark"
  legend-enabled
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

Custom Center and Zoom

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  center="-118.24,34.05"
  zoom="12"
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

Disable Scroll Zoom (For Inline Content)

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  scroll-enabled="false"
  style="width: 100%; height: 400px;">
</arcgis-embedded-map>

With API Key

<arcgis-embedded-map
  item-id="YOUR_ITEM_ID"
  api-key="YOUR_API_KEY"
  portal-url="https://www.arcgis.com"
  legend-enabled
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

Enterprise Portal

<arcgis-embedded-map
  item-id="YOUR_ENTERPRISE_ITEM_ID"
  portal-url="https://your-enterprise.com/portal"
  heading-enabled
  legend-enabled
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

CDN Full Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Embedded Map</title>
  <script src="https://js.arcgis.com/5.0/"></script>
  <script type="module" src="https://js.arcgis.com/5.0/embeddable-components/"></script>
  <style>
    body { font-family: sans-serif; max-width: 900px; margin: 0 auto; padding: 20px; }
    arcgis-embedded-map { width: 100%; height: 500px; display: block; margin: 20px 0; }
  </style>
</head>
<body>
  <h1>City Demographics</h1>
  <p>Explore population data across the region.</p>
  <arcgis-embedded-map
    item-id="f2e9b762544945f390ca4ac3671cfa72"
    heading-enabled
    legend-enabled
    bookmarks-enabled
    theme="light">
  </arcgis-embedded-map>
  <p>Data source: US Census Bureau</p>
</body>
</html>

Programmatic Configuration

Setting Extent via JavaScript

const embeddedMap = document.querySelector("arcgis-embedded-map");
await embeddedMap.componentOnReady();

embeddedMap.extent = {
  xmin: -118.5,
  ymin: 33.8,
  xmax: -117.9,
  ymax: 34.3,
  spatialReference: { wkid: 4326 }
};

Using a WebMap Instance

const WebMap = await $arcgis.import("@arcgis/core/WebMap.js");

const webMap = new WebMap({
  portalItem: { id: "f2e9b762544945f390ca4ac3671cfa72" }
});

const embeddedMap = document.querySelector("arcgis-embedded-map");
embeddedMap.webMap = webMap;

Theming with CSS Variables

The component supports Calcite Design System CSS variables:

arcgis-embedded-map {
  --calcite-color-brand: #007ac2;
  --calcite-color-foreground-1: #ffffff;
  --calcite-color-text-1: #151515;
  --calcite-color-border-1: #cacaca;
}

Common Pitfalls

Missing item-id: The component requires a WebMap portal item ID.

<!-- Anti-pattern: no item-id -->
<arcgis-embedded-map style="width: 800px; height: 600px;">
</arcgis-embedded-map>

<!-- Correct: provide item-id -->
<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  style="width: 800px; height: 600px;">
</arcgis-embedded-map>

Impact: The component renders an empty container with no map.

Missing embeddable-components script: The package must be loaded separately.

<!-- Anti-pattern: only loading core SDK -->
<script src="https://js.arcgis.com/5.0/"></script>
<arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>

<!-- Correct: load embeddable-components -->
<script src="https://js.arcgis.com/5.0/"></script>
<script type="module" src="https://js.arcgis.com/5.0/embeddable-components/"></script>
<arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>

Impact: The element is unrecognized and renders as empty.

No explicit size: The embedded map needs width and height to render visibly.

<!-- Anti-pattern: no size set -->
<arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>

<!-- Correct: explicit dimensions -->
<arcgis-embedded-map
  item-id="abc123"
  style="width: 100%; height: 500px; display: block;">
</arcgis-embedded-map>

Impact: The map renders with zero height and is invisible on the page.

Using arcgis-embedded-map for interactive apps: This component is designed for simple embeds. It does not support custom widgets, editing, layer manipulation, or programmatic view control. Use arcgis-map from @arcgis/map-components for full applications.

Impact: Attempting to add widgets or edit features fails silently.
Scroll zoom in long pages: When the embedded map is inline with scrollable content, scroll zoom can trap users. Disable it for better UX.
```
<arcgis-embedded-map
  item-id="abc123"
  scroll-enabled="false"
  style="width: 100%; height: 400px;">
</arcgis-embedded-map>
```
Impact: Users get stuck zooming the map when they want to scroll the page.

Reference Samples

Search for embedded map samples demonstrating lightweight WebMap embedding.

Related Skills

See arcgis-core-maps for full-featured map applications using arcgis-map and arcgis-scene.
See arcgis-starter-app for project scaffolding and CDN setup.
See arcgis-authentication for API key and portal authentication.

Repository: SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context
Commit: d84407b

Last updated: 1 day ago
Created: 1 day ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.