The Complete Guide to
The Map Widget

What IS the Map widget and why it matters

The Map widget is the centerpiece of most Experience Builder apps. It displays your Web Map (or Web Scene), lets users pan, zoom, click, and select features, and -- most importantly -- it drives other widgets. When a user clicks a feature on the map, that selection can update a List, populate a Text widget, filter a Chart, and trigger message actions across the entire app.

Without a Map widget, your EB app is a static page. With one, it becomes an interactive application.

Adding a Map widget and connecting a Web Map

The single most important rule of the Map widget: build your Web Map in Map Viewer first, then connect it in EB. Do not try to configure layers, symbology, or popups inside Experience Builder. EB reads from your Web Map. If you want to change how data looks, change the Web Map.

The Map tools toolbar

Every Map widget has a configurable toolbar that appears in the corner of the map. These are the built-in tools your users get. You choose which to show and which to hide. The key is knowing which tools are actually useful and which just add clutter.

Layer visibility: Layer List and Legend

Users often need to toggle layers on and off or see what the colors on the map mean. You have two approaches: built-in tools (inside the Map toolbar) or standalone widgets (separate widgets connected to the Map). The standalone widgets are almost always better.

Connecting a standalone Layer List to your Map:

Bookmarks and initial extent

When your app loads, the map zooms to a specific place. That is the initial extent. You can also create bookmarks -- saved views that users can jump to. Both are more useful than people realize.

Setting the initial extent in EB:

Creating and using bookmarks:

Bookmarks can be created in Map Viewer (saved with the Web Map) or in the Bookmark widget in EB. Map Viewer bookmarks are the better approach because they persist with the Web Map and work everywhere.

Selection tools

Selection is the foundation of interactivity in EB. When a user selects features on the map, that selection flows to every connected widget. A List shows only the selected items. A Text widget updates to reflect the selection. A Chart recalculates. Without selection, your app is just a viewer. With selection, it becomes an analytical tool.

Search widget integration

Search is how users find specific features or addresses on the map. You can use the built-in search tool on the Map toolbar, or the standalone Search widget. The standalone version gives you far more control over search sources, appearance, and behavior.

Configuring the standalone Search widget:

Multiple maps in one app

Sometimes one map is not enough. You might want to show two time periods side by side, or display different themes (demographics vs. infrastructure) simultaneously. EB supports multiple Map widgets in the same app, each with its own Web Map.

Setting up synced maps:

Connecting maps to filters and lists

This is where EB starts to feel like a real application. The pattern is: Map displays data, Filter narrows it, List shows details. All three widgets share the same data source, and they stay in sync automatically.

The data connection model:

In EB, widgets do not connect directly to each other (in most cases). They connect to a shared data source. When the Map widget is connected to a Web Map, EB creates data sources for each layer. Other widgets connect to these same data sources. When a Filter widget filters the data source, every widget connected to that source updates.

Popups: configure them in Map Viewer, not EB

This is the lesson that will save you the most time. Popups belong in the Web Map, not in EB. Yes, EB has popup settings. Yes, you can override them. No, you should not. Here is why.

What to configure in Map Viewer's popup settings:

// Arcade expression in a popup: shelter capacity status
var current = $feature.CURRENT_POP
var capacity = $feature.CAPACITY
var pct = Round((current / capacity) * 100, 0)

var status = "Available"
if (pct > 90) { status = "Near Capacity" }
if (pct >= 100) { status = "FULL" }

return pct + "% full (" + status + ")"

Click-to-detail: side panel patterns

Popups are fine for quick info, but for a real application, you want a detail panel -- a sidebar or bottom panel that shows full information about the clicked feature. This is the most professional-looking pattern in EB apps and it replaces the floating popup entirely.

Building a click-to-detail panel:

Web Scenes and 3D

The Map widget can display Web Scenes (3D) in addition to Web Maps (2D). When you connect a Web Scene, the widget becomes a 3D viewer with tilt, rotation, and elevation. This is powerful for specific use cases, but 3D comes with tradeoffs.

Common Map widget gotchas

This lesson is the one you'll come back to. These are the issues that waste hours and aren't documented well. Every one of these has bitten experienced EB developers.

URL parameters for map state

URL parameters let you deep link to a specific map state: a particular extent, selected features, or filtered view. This is how you share "look at this specific area" links or embed map views in emails and reports.

EB supports several URL parameters out of the box. You append them to your app URL with ? for the first and & for additional parameters.

// Center on Washington DC at zoom level 12
https://experience.arcgis.com/experience/abc123?center=-77.03,38.89&level=12

// Show a specific extent (bounding box)
https://experience.arcgis.com/experience/abc123?extent=-78.5,38.0,-76.5,39.5

// Open a specific page in a multi-page app
https://experience.arcgis.com/experience/abc123?page=page-2

// Combine parameters
https://experience.arcgis.com/experience/abc123?center=-77.03,38.89&level=14&page=detail

Performance optimization

A slow map kills your app. Users will wait maybe 3 seconds for a map to load. After that, they leave. Performance optimization is not optional for production apps -- it is a requirement. Here is what actually moves the needle.

Concrete optimization strategies:

Multi-source maps

Production maps often combine data from multiple sources: your org's hosted layers, Living Atlas layers, external WMS/WFS services, CSV files, and GeoJSON. Understanding how to combine them -- and the authentication implications -- is essential for real-world apps.

// Useful Living Atlas layers to add to your Web Map:

USA Counties          // County boundaries with FIPS codes
USA States           // State boundaries
USA Census Tracts    // Tract-level demographics
USA Social Vulnerability Index  // CDC SVI data
World Imagery        // Satellite basemap
USA Flood Hazard Areas  // FEMA flood zones
USA Weather Watches and Warnings  // Live NWS alerts
USA Wildfires        // Active fire perimeters
USA Red Cross Regions  // ARC organizational boundaries

Real-world patterns: disaster response maps

This lesson brings everything together with production patterns from actual disaster response EB apps. These are the map configurations and widget connections that power real operational tools.

Pattern 1: Shelter Status Map

A map showing shelter locations with color-coded status indicators. Green = Open, Yellow = Near Capacity, Red = Closed. Click a shelter to see capacity details in a side panel.

// Shelter capacity popup expression
var current = $feature.CURRENT_POP
var capacity = $feature.CAPACITY

if (IsEmpty(capacity) || capacity == 0) {
  return "Capacity not set"
}

var pct = Round((current / capacity) * 100, 0)
var remaining = capacity - current
var indicator = IIf(pct > 90, "CRITICAL",
  IIf(pct > 75, "Filling up", "Available"))

return pct + "% occupied (" + current + "/" + capacity + ") - " + indicator
  + "\n" + remaining + " spots remaining"

Pattern 2: Damage Assessment Map

Damage assessment data with classification-based symbology and a dashboard-style summary. Rectangle selection for area-based analysis.

Pattern 3: Evacuation Zone Map

Polygon zones with interactive zone lookup. Users search an address or click the map to find which zone they're in.

The Map widget as app controller

The most powerful EB architecture puts the Map widget at the center of everything. Every other widget responds to what's visible on the map. When the user pans, zooms, or selects, the entire app updates. This is the map-centric app architecture, and it is the professional standard for operational GIS dashboards.

The three map triggers that drive other widgets:

Building a map-centric dashboard:

// This Arcade expression respects spatial filtering
// When the user pans/zooms, the stats update automatically

function getFilteredFeatureSet(ds) {
  var result = ds.layer
  var qp = ds.queryParams
  if (!IsEmpty(qp.where)) { result = Filter(result, qp.where) }
  if (!IsEmpty(qp.geometry)) { result = Intersects(result, qp.geometry) }
  return result
}

var ds = $dataSources["YOUR_DS_ID"]
var filtered = getFilteredFeatureSet(ds)
var selected = ds.selectedFeatures
var target = IIf(Count(selected) > 0, selected, filtered)

var count = Count(target)
var label = IIf(Count(selected) > 0, "Selected", "In view")

return '<p style="font-size:28px;font-weight:bold;margin:0;">'
  + Text(count, '#,###')
  + '</p><p style="font-size:12px;color:#888;margin:2px 0 0;">'
  + label + ' features</p>'