Popup

A collection of action button or action toggle objects. Each action may be executed by clicking the icon or image symbolizing them.

By default, popups have a Zoom To action styled with a magnifying glass icon. When this icon is clicked, the view zooms in four LODs and centers on the selected feature. You may remove this default action by setting includeDefaultActionsDisabled to true, or by setting the overwriteActions property to true in a PopupTemplate.

The order of each action is the order in which they appear in the actions Collection.

The arcgisTriggerAction event fires each time an action is clicked.

See also

• arcgisTriggerAction

Example

1
2
3
4
5
6
7
8
9
10
11
12
// Defines an action button to zoom out from the selected feature
const zoomOutAction = {
  type: "button",
  // This text is displayed as a tooltip
  title: "Zoom out",
  // The ID by which to reference the action in the event handler
  id: "zoom-out",
  // Sets the icon used to style the action button
  icon: "magnifying-glass-minus"
};
// Adds the custom action to the popup.
popupComponent.actions.push(zoomOutAction);

Indicates if the component is active when it is visible and is not waiting.

Default value

false

Position of the popup in relation to the selected feature. The default behavior is to display above the feature and adjust if not enough room. If needing to explicitly control where the popup displays in relation to the feature, choose an option besides auto.

Example

1
2
// Popup will display on the bottom-right of the selected feature regardless of where that feature is located
popupComponent.alignment = "bottom-right";

Attribute

alignment

Default value

"auto"

This closes the popup when the View camera or Viewpoint changes.

Attribute

auto-close-enabled

Default value

false

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy method when you are done to prevent memory leaks.

Attribute

auto-destroy-disabled

Default value

false

Indicates whether the popup displays its content. If true, only the header displays.

Default value

false

The content of the popup. When set directly on the Popup, this content is static and cannot use fields to set content templates. To set a template for the content based on field or attribute names, see PopupTemplate.content.

Example

1
2
3
// This sets generic instructions in the popup that will always be displayed
// unless it is overridden by a PopupTemplate
popupComponent.content = "Click a feature on the map to view its attributes";

Attribute

content

Dock position in the arcgis-map, arcgis-scene, or arcgis-link-chart component.

Enables automatic creation of a popup template for layers that have popups enabled but no popupTemplate defined. Automatic popup templates are supported for layers that support the createPopupTemplate method. (Supported for FeatureLayer, GeoJSONLayer, OGCFeatureLayer, SceneLayer, CSVLayer, PointCloudLayer, StreamLayer, ImageryLayer, and VoxelLayer).

Note:

• Starting with version 4.12, PopupTemplate content can no longer be set using a wildcard, e.g. *. Instead, set the defaultPopupTemplateEnabled property to true.
• Starting with 4.16, the default popup has been improved to no longer display system fields that do not hold significant value, e.g. Shape__Area and Shape__Length are two fields that no longer display.
• Starting with version 4.28, date fields are formatted using the short-date-short-time preset dateFormat rather than long-month-day-year in default popup created by setting the defaultPopupTemplateEnabled property to true. For example, previously a date that may have appeared as "December 30, 1997" will now appear as "12/30/1997 6:00 PM".

Attribute

default-popup-template-enabled

Default value

false

Indicates whether the placement of the popup is docked to the side of the view.

Docking the popup allows for a better user experience, particularly when opening popups in apps on mobile devices. When a popup is "dockEnabled" it means the popup no longer points to the selected feature or the location assigned to it. Rather it is attached to a side, the top, or the bottom of the view.

See dockOptions to override default options related to docking the popup.

Examples

1
2
<!-- Setting this property in HTML -->
<arcgis-popup dock-enabled></arcgis-popup>

1
2
3
// Setting this property using JS.
// The popup will automatically be dockEnabled when made visible
popupComponent.dockEnabled = true;

Attribute

dock-enabled

Default value

false

Docking the popup allows for a better user experience, particularly when opening popups in apps on mobile devices. When a popup is "dockEnabled" it means the popup no longer points to the selected feature or the location assigned to it. Rather it is placed in one of the corners of the view or to the top or bottom of it. This property allows the developer to set various options for docking the popup.

See the object specification table below to override default docking properties on the popup.

Example

1
2
3
4
5
6
7
8
9
popupComponent.dockOptions = {
  // Disable the dock button so users cannot undock the popup
  buttonEnabled: false,
  // Dock the popup when the size of the view is less than or equal to 600x1000 pixels
  breakpoint: {
    width: 600,
    height: 1000
  }
};

The number of selected features available to the popup.

Default value

0

This property enables showing a list of features. Setting this to true allows the user to scroll through the list of features. This value will only be honored if initialDisplayMode is set to "feature".

Attribute

feature-menu-open

Default value

false

An array of features associated with the popup. Each graphic in this array must have a valid PopupTemplate set. They may share the same PopupTemplate or have unique PopupTemplates depending on their attributes. The content and title of the popup is set based on the content and title properties of each graphic's respective PopupTemplate.

When more than one graphic exists in this array, the current content of the Popup is set based on the value of the selected feature.

This value is null if no features are associated with the popup.

Example

1
2
3
4
5
6
7
8
9
10
11
12
// When setting the features property, the graphics pushed to this property
// must have a PopupTemplate set.
let g1 = new Graphic();
g1.popupTemplate = new PopupTemplate({
  title: "Results title",
  content: "Results: {ATTRIBUTE_NAME}"
});
// Set the graphics as an array to the popup instance. The content and title of
// the popup will be set depending on the PopupTemplate of the graphics.
// Each graphic may share the same PopupTemplate or have a unique PopupTemplate
let graphics = [g1, g2, g3, g4, g5];
popupComponent.features = graphics;

This function provides the ability to override either the arcgis-map.goTo or arcgis-scene.goTo methods.

Example

1
2
3
4
5
6
popupComponent.goToOverride = (viewElement, goToParams)=>  {
  goToParams.options = {
    speedFactor: 2
  };
  return viewElement.goTo(goToParams.target, goToParams.options);
};

The title of the popup. This can be set generically on the popup no matter the features that are selected. If the selected feature has a PopupTemplate, then the title set in the corresponding template is used here.

See also

• headingLevel

Examples

1
2
3
<!-- This title will display in the popup unless a selected feature's
    PopupTemplate overrides it -->
<arcgis-popup heading="Population by zip codes in Southern California"></arcgis-popup>

1
2
3
// This title will display in the popup unless a selected feature's
// PopupTemplate overrides it
popupComponent.title = "Population by zip codes in Southern California";

Attribute

heading

Indicates the heading level to use for the heading of the popup. By default, the heading is rendered as a level 2 heading (e.g. <h2>Popup title</h2>). Depending on the component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also

• Heading Elements
• heading

Example

1
2
<!-- Render the popup heading as a level 3 heading -->
<arcgis-popup heading="Popup title" heading-level="3"></arcgis-popup>

Attribute

heading-level

Default value

2

Indicates whether to hide the action bar that holds the feature's actions.

Attribute

hide-action-bar

Default value

false

Indicates whether to hide the close button in the component.

Attribute

hide-close-button

Default value

false

Indicates whether to hide the collapse button in the component.

Attribute

hide-collapse-button

Default value

false

Indicates whether to hide the group heading for a list of multiple features in the feature menu.

Attribute

hide-feature-list-layer-title

Default value

false

Indicates whether to hide a heading and description on the component feature menu list.

Attribute

hide-feature-menu-heading

Default value

false

Indicates whether pagination for feature navigation will be displayed. This allows the user to scroll through various selected features using pagination arrows.

Attribute

hide-feature-navigation

Default value

false

Indicates whether to hide the heading in the component.

Attribute

hide-heading

Default value

false

Indicates whether to hide the spinner in the component.

Attribute

hide-spinner

Default value

false

Indicates if the selected feature will be highlighted. This is done using the arcgis-map.highlights or the arcgis-scene.highlights.

Attribute

highlight-disabled

Default value

false

Indicates whether to include the default actions in the component. In order to disable any default actions, it is necessary to set includeDefaultActionsDisabled to true.

Attribute

include-default-actions-disabled

Default value

false

Indicates whether to initially display a list of features, or the content for one feature.

Attribute

initial-display-mode

Default value

"feature"

The component's default label.

Attribute

label

Point used to position the popup. This is automatically set when viewing the popup by selecting a feature. If using the Popup to display content not related to features in the map, such as the results from a task, then you must set this property before making the popup visible to the user.

Examples

1
2
3
4
// Sets the location of the popup to the center of the view
popupComponent.location = viewELement.center;
// Displays the popup
popupComponent.visible = true;

1
2
3
// Sets the location of the popup to a specific place (using autocast)
// Note: using latitude/longitude only works if view is in Web Mercator or WGS84 spatial reference.
popupComponent.location = {latitude: 34.0571, longitude: -117.1968};

1
2
3
4
5
6
// Sets the location of the popup to the location of a click on the view
reactiveUtils.on(()=>viewElement, "arcgisViewClick", (event)=>{
  popupComponent.location = event.detail.mapPoint;
  // Displays the popup
  popupComponent.visible = true;
});

Overwrite localized strings for this component

An array of pending Promises that have not yet been fulfilled. If there are no pending promises, the value is null. When the pending promises are resolved they are removed from this array and the features they return are pushed into the features array.

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

• Associate components with a Map or Scene component

Attribute

reference-element

The feature that the component has drilled into. This feature is either associated with the selected feature in a relationship or utility network element.

The selected feature accessed by the popup. The content of the Popup is determined based on the PopupTemplate assigned to this feature.

Returns a reference to the current arcgis-feature that the Popup is using. This is useful if needing to get a reference to the component in order to make any changes to it.

Index of the feature that is selected. When features are set, the first index is automatically selected.

Attribute

selected-feature-index

The current state of the component.

Attribute

state

Default value

"disabled"

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the Popup component will be associated with a map or scene component rather than using the view property.

Indicates whether the popup is visible. This property is true when the popup is querying for results, even if it is not open. Use the property to check if the popup is visible.

Attribute

visible

Default value

false

Removes all promises, features, content, heading and location from the Popup.

Returns

Promise<void>

Create a promise that resolves once component is fully loaded.

Example

1
2
3
4
const arcgisPopup = document.querySelector("arcgis-popup");
document.body.append(arcgisPopup);
await arcgisPopup.componentOnReady();
console.log("arcgis-popup is ready to go!");

Returns

Promise<void>

Permanently destroy the component.

Returns

Promise<void>

Use this method to return feature(s) at a given screen location. These features are fetched from all of the LayerViews in the view. In order to use this, a layer must already have an associated PopupTemplate and have its popupEnabled.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example showing how to use fetchFeatures in an application
// with the popup and feature components.
const popupComponent = document.querySelector("arcgis-popup");
const viewElement = document.querySelector("arcgis-map");
const featureComponent = document.querySelector("arcgis-feature");
// Get viewElement's click event
reactiveUtils.on(()=>viewElement, "arcgisViewClick", (event)=>{
  const { screenPoint } = event.detail;
  // Call fetchFeatures on the popup and pass in the click event screenPoint
  popupComponent.fetchFeatures(screenPoint).then((response) => {
    // Access the response from fetchFeatures
    response.allGraphicsPromise.then((graphics) => {
      // Set the feature component's graphic to the returned graphic from fetchFeatures
      featureComponent.graphic = graphics[0];
    });
  });
});

Parameters

Returns

Promise<FetchPopupFeaturesResult>

Selects the feature at the next index in relation to the selected feature.

See also

• selectedFeatureIndex

Returns

Promise<FeaturesViewModel>

Opens the popup at the given location with content defined either explicitly with content or driven from the PopupTemplate of input features. This method sets the popup's visible property to true. Users can alternatively open the popup by directly setting the visible property to true.

Note: The popup will only display if the arcgis-map or arcgis-scene size constraints in dockOptions are met or the location property is set to a geometry.

See also

• visible

Examples

1
2
3
4
5
6
7
8
reactiveUtils.on(()=>viewElement, "arcgisViewClick", (event)=>{
 const { mapPoint } = event.detail;
  popupComponent.open({
   location: mapPoint,  // location of the click on the view
   title: "You clicked here",  // title displayed in the popup
   content: "This is a point of interest"  // content displayed in the popup
  });
});

1
2
3
4
5
6
7
reactiveUtils.on(()=>viewElement, "arcgisViewClick", (event)=>{
   const { mapPoint } = event.detail;
   popupComponent.open({
     location: mapPoint,  // location of the click on the view
     fetchFeatures: true // display the content for the selected feature if a popupTemplate is defined.
   });
 });

1
2
3
4
5
6
7
popupComponent.open({
  title: "You clicked here",  // title displayed in the popup
  content: "This is a point of interest",  // content displayed in the popup
  location: event.detail.mapPoint,
  updateLocationEnabled: true  // updates the location of popup based on
  // selected feature's geometry
});

1
2
3
4
5
popupComponent.open({
  features: graphics,  // array of graphics
  featureMenuOpen: true, // selected features initially display in a list
  location: graphics[0].geometry // location of the first graphic in the array of graphics
});

Parameters

Returns

Promise<void>

Selects the feature at the previous index in relation to the selected feature.

See also

• selectedFeatureIndex

Returns

Promise<FeaturesViewModel>

Use this method to give focus to the component if the component is able to be focused.

Returns

Promise<void>

Triggers the arcgisTriggerAction event and executes the action at the specified index in the actions array.

Parameters

Returns

Promise<void>

Emitted when the component's close button is clicked.

Emitted when the component associated with a map or scene view is ready to be interacted with.

Fires after the user clicks on an action in the Popup component. This event may be used to define a custom function to execute when particular actions are clicked.

See also

• actions
• PopupTemplate.actions
• open()

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
viewElement.addEventListener("arcgisViewClick", (event) => {
  const { mapPoint } = event.detail;
  popupComponent.open({
    location: mapPoint,
    fetchFeatures: true,
    actions: [{
      // This text is displayed as a tooltip
      title: "Zoom out",
      // The ID used to reference this action in the event handler
      id: "zoom-out",
      // Sets the icon font used to style the action button
      icon: "magnifying-glass-minus"
    },
    {
      title: "Delete Feature",
      id: "delete-feature-action",
      icon: "trash"
    }]
  });
});

// Fires each time an action is clicked
reactiveUtils.on(()=> popupComponent, "arcgisTriggerAction", (event)=>{
  // If the zoom-out action is clicked, execute the following code
  if(event.detail.action.id === "zoom-out"){
    // Zoom out two levels (LODs)
    viewElement.goTo({
      center: viewElement.center,
      zoom: viewElement.zoom - 2
    });
  }
});