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.
