Map widget

The Map widget allows you to display 2D and 3D geographic information. You can enable tools in the map, such as Zoom, Locate, Search, and Measure.

Examples

Use this widget to support app design requirements such as the following:

• You need to show the comparison of a map in 2D and 3D. You can add two Map widgets and create a trigger and action to synchronize views when interacting with either map.
• You want to click a feature on the map and display the record in a Feature Info widget.
• You have a requirement to filter a List widget based on clicking a feature on the map.

Usage notes

You can show a single map or include the option to switch between two maps. You can include multiple maps in an app by adding more Map widgets.

The Map widget requires a data source, including web maps and web scenes. When you include tools, they are automatically positioned on the map based on the size of the widget in both design mode and the final app.

Tip:

If you have a web map or web scene with multiple layers and you want to designate which layers are displayed by default in different Map widgets, you can add the same web map or web scene multiple times on the Data tab, choose to hide different sublayers on each map or scene copy, and connect each copy to a different Map widget.

Learn more about how to configure layer visibility from one map and use it with different Map widgets

Settings

The Map widget includes the following settings:

• Select map—Add a data source for web maps and web scenes.
• Initial view—Set the initial position of the map when it loads in the widget.
  • Default—Use the positioning of the map inherited from the web map or web scene.
  • Custom—Modify the initial view by creating a custom position for the map.
• Tools—Include tools for users to interact with the map.
  • Zoom—Zoom in and out on the map.
  • Home—Zoom the map to the initial map position (extent).
  • Navigation—Include map panning and rotating tools. These tools appear when the Map widget is displaying a 3D web scene.
  • Locate—Display the user’s current location.
  • Compass—Indicate where north is in relation to the current view of a 2D or 3D map.
  • Search—Find locations based on a geocoding service from your organization or portal. If you turn on pop-ups, pop-ups appear for search results.
  • Layers—Display a list of layers and symbols in the map and allow users to turn them on or off.
  • Basemap—Display a gallery of basemaps.
  • Measure—Include measurement tools for measuring area and distance. The Measure tool uses snapping—the pointer snaps to features on the map. When measuring, users can press and hold the Ctrl key to temporarily turn off snapping.
  • Fullscreen—Display the map using the entire screen.
  • Scale bar—Include a scale bar on the map that displays units in metric or nonmetric values and dynamically responds to various coordinate systems.
  • Select—Select features on the map using different selection tools and selection modes. Users have access to the following selection tools and can select features that are either completely contained by or partially or completely within drawn polygons.
    • Rectangle—Click and drag to draw a rectangle across features.
    • Lasso—Click the map to create the vertices of a polygon, or draw with the pointer to create a freehand shape. Double-click to close the polygon and select contained features.
    • Circle—Click and drag to draw a circle across features.
    • Line—Click the map to create the vertices of a line. Double-click to end the line and select intersecting features.
    • Point—Click the map to place a point and select intersecting features.

    Users can select multiple features in the following four ways:

    • Create a selection of features with each new selection tool drawing. This is the default.
    • Add to the current selection set (press Shift while drawing).
    • Remove features from the current selection set (press Ctrl while drawing for Windows; press Cmd while drawing for Mac).
    • Select features from the current selection set (press Ctrl+Shift while drawing for Windows; Cmd+Shift while drawing for Mac).

    When the user makes a selection, the selection tool icon becomes a progress icon. If the user selects a large number of features, the selection process may take a long time. Users can click the progress button to stop the selection process.

  • Extent navigate—Go back and forth through the extents that the user has visited at run time.
  • Overview map—Add an expandable inset map. The overview map is a smaller version of the main map with a locator rectangle that depicts the main map extent. If you click and drag the locator rectangle, the main map zooms to that new location. This tool does not appear on small screen layouts.
• Tools layout—Select a layout for the map tools on large and medium screen devices.

  Note:

  The Map widget automatically hides tools depending on the widget's height to make the widget more responsive to medium and small screen devices. For example, if a Map widget's height is smaller than 465 pixels, the Measure and Locate tools are hidden on small and medium screens even if they are turned on in the widget's settings. As the widget's height decreases, more tools are hidden. The Fullscreen, Search, Zoom, Scale bar, and Compass tools are the last to disappear.

• Options
  • Feature selection colors—Change the highlight color and transparency for features selected on the map. You can customize the highlight fill and outline.
  • Enable scroll zooming—Enable mouse wheel zooming and, on touch screens, single-finger map panning.
  • Enable pop-up—Enable pop-ups on the map. If your app also includes a Feature Info widget, you may want to turn off this setting. If a data source has related data and you configure related records in pop-ups in Map Viewer, you can view related records in pop-ups in Experience Builder.
    • Show pop-up upon feature selection—Show pop-ups on the map when the user selects map features in another widget, such as a table or list.
    • Dock the pop-up—Make pop-ups appear at a specific corner or side of the map.
      • Position—You can make pop-ups appear at the Default docked position, or switch to Custom and choose one of six anchor points within the frame of the Map widget. The default position is the top right corner of the map on large- and medium-screen devices and the bottom of the map on small-screen devices. At run time, users can still click Dock and Undock on the pop-up window to change where pop-ups appear.

        Note:

        If you previously set the docked pop-up position to the top right corner, after the November 2024 update the position is now set to Default.

  • Scene quality mode (for web scenes)—Control the quality of the web scene by balancing the visual effect and loading efficiency.
    • Low—Increase performance, stability, and speed by reducing data load.
    • Medium—Equally optimize performance and quality.
    • High—Improve the quality of visualization options (such as water reflection).
• Enable client-side query—Turn on these toggle buttons to have widgets in the app use client-side queries to work with data from your web maps. If you connect the same web map to multiple Map widgets, you only have to turn on client-side queries for a web map once.

  Note:

  Web scenes do not support client-side queries.

  The advantages of client-side queries are decreased demand on the server and improved app performance. Client-side queries greatly reduce the number of network requests made to a server. In addition, client-side queries are faster than server-side queries. Data-related tasks, such as selecting a feature to update a chart, perform faster.

  The disadvantage of client-side queries is that map features take longer to load when you change the map extent.

  Note:

  A common Experience Builder app configuration that can be demanding on servers is a List widget that updates based on the current map extent.

  To avoid overloading servers, it is recommended that you turn on client-side queries if you configure a Map widget with the Extent changes trigger and Filter data records message action or any other action that involves frequent changes of the map extent. This is especially important if you expect many users to access an app at the same time.

  Note:

  For known limitations of client-side queries, see ArcGIS Maps SDK for JavaScript documentation.

Interaction options

The Map widget supports setting triggers on the Action tab of the widget's settings. You can synchronize two Map widgets by adding an Extent changes trigger to both maps, selecting the other map as the target for both, and choosing the Pan to and Zoom to actions. For web maps, the Zoom to synchronization includes the map's rotate behavior. For web scenes, it includes the rotate and tilt behaviors.

Note:

If a Map widget is configured with both the Zoom to and Pan to actions, the Zoom to action takes precedence over Pan to. This means that if the user pans and zooms the map at the same time, the Pan to action is ignored.

You can set triggers and message actions to have a map interact with other widgets. For example, you can add an action trigger to make a List widget show only the features that are visible on the map. The Map widget also supports data actions, which appear in pop-ups and allow users to export data, view records in a table, and more. Triggers, message actions, and data actions are defined and managed on the Action tab of the widget's settings.

You can use the Show on map message and data actions to view features from another widget in a Map widget. If you do, features that you add to the map also appear in map layer lists. When you add a Show on map action, you can customize the symbols for records.

• Use custom symbols—Customize the fill, outline, transparency, and more for points, lines, and polygons.
• Use layer defined symbols—Use symbols from the layers associated with the current action in the source widget.
• Set as operational layers—If you turn on this setting, pop-ups can appear for these layers when users click features at run time.

If you configure another widget to target the Map widget with the Record selection changes trigger and the Zoom to or Pan to action, you can turn on Return to the initial map extent when selection is cleared. If you do, the map automatically zooms or pans back to its initial extent once you remove the selection.

Some message actions, including Zoom to and Pan to, prompt you to choose trigger data. Trigger data is the data source that triggers the message action. You can choose one of the following options:

• All data—A trigger occurs when the user interacts with any of the data sources connected to the source widget.
• Customized data—Use specific layers as trigger data. Custom trigger data is useful if you only want a specific data source to trigger the message action.

When you configure the Record selection changes trigger to target the Map widget with the Flash or Filter actions, you are prompted to choose a connection mode. You can choose one of the following options:

• Automatic—The selected data will flash or filter if the data from the source widget is connected to the Map widget. The trigger and action data are from the same layer and are automatically bound.
• Customize—Use specific layers as trigger and action data. You can set a trigger and action data connection.

To learn more about the Map widget's supported actions, see Add actions to widgets.

URL parameters

The subsections below describe map-related URL parameters. You can use the settings under Manage URL status to make these parameters appear in the URL when the user interacts with the Map widget. All of the Map widget's parameters follow hashmarks (#). To include multiple parameters, you must separate them with ampersands (&).

Note:

The Map widget's center, scale, and rotation parameters only work with web maps, not web scenes.

Define the web map or web scene for when a Map widget first loads

If your Map widget contains multiple web maps or web scenes, you can define which one is active when the app loads using active_datasource_id followed by the desired item's data source ID. The following are examples:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>

https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4

Center a map

To center a map on a particular location, use center followed by the desired coordinates and the desired coordinate system's well-known ID (WKID). The following are examples:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=center:<x,y,wkid>

https://experience.arcgis.com/experience/<AppId>#map_1=center:-10373125.398783844%2C4598516.55871741%2C102100

Define the map scale

To define the map scale, use scale followed by a scale value. The following are examples:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>

https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833

Define the map rotation

To define the map rotation, use rotation followed by a number of degrees. The following are examples:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>

https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45

Define the map viewpoint

To define the viewpoint, which is the location or camera position from which to view the map or scene, use viewpoint. If your map widget contains multiple maps or scenes, the viewpoint parameter affects all of them.

Viewpoints and their properties are typically written in JSON format, as in the following example:

 {
  "rotation": 0,
  "scale": 19966005.903731048,
  "targetGeometry": {
    "spatialReference": {
      "latestWkid": 3857,
      "wkid": 102100
    },
    "x": -9870655.016044471,
    "y": 4724533.527708739
  }
}

To define a specific viewpoint using the URL, you must encode all of those properties typically written in JSON format into the URL. The following is an example:

https://experience.arcgis.com/experience/<AppId>#map_1=viewpoint:%7B"rotation"%3A0%2C"scale"%3A24387741.012671936%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-10078461.002935613%2C"y"%3A4523117.553838721%7D%7D

Note:

The center, scale, and rotation parameters have higher priorities than the viewpoint parameter and will override it if you use multiple parameters related to a web map.

Note:

Map extent changes caused by message actions have a higher priority than extent changes caused by URL parameters. For example, if you try to open a Map widget to predefined extents using the above URL parameters, but the Map widget is also configured as the target of the Record selection changes trigger and Pan to or Zoom to message actions, the extents associated with the message actions supersede the extents you set with URL parameters.

Define visibility for map layers

To define layer visibility for a map's layers, use layer_visibility.

Layer visibility is typically written in JSON format, as in the following example:

 {
  "widget_1-dataSource_1": {
    "widget_1-dataSource_1-187938b7328-layer-2": false
  },
  "widget_1-dataSource_4": {
    "widget_1-dataSource_4-18a690b433a-layer-4": false
  }
}

To make layers in your map visible or hidden using the URL, you must encode all of the information into the URL after the layer_visibility parameter. The following is an example:

https://experience.arcgis.com/experience/<AppId>#map_1=layer_visibility:%7B%22widget_1-dataSource_1%22%3A%7B%22widget_1-dataSource_1-187938b7328-layer-2%22%3Afalse%7D%2C%22widget_1-dataSource_4%22%3A%7B%22widget_1-dataSource_4-18a690b433a-layer-4%22%3Afalse%7D%7D

Zoom or pan to selected features

The data_s parameter appears in the app URL when you select one feature or multiple features. You can use the zoom_to_selection parameter to zoom or pan to your selection. Add zoom_to_selection=true to the app URL to zoom all maps to the selection. Add zoom_to_selection=false to the URL to pan all maps to the selection.

The zoom_to_selection parameter works with all three selection types: selections based on recordID (id), selections based on features' locations relative to other features (geometry), and selections based on attributes (where). The following are examples:

https://experience.arcgis.com/experience/<AppId>/#data_s=id:<data source ID>:<OBJECTID>&zoom_to_selection=true

https://experience.arcgis.com/experience/<AppId>/#data_s=id%3AdataSource_1-csv_905%3A77&zoom_to_selection=true

Note:

Imagery layers only support selecting by id.

Note:

If the URL contains the data_s parameter and any of the Map widget parameters, the Map widget parameters have the higher priority.