import PopupViewModel from "@arcgis/core/widgets/Popup/PopupViewModel.js";const PopupViewModel = await $arcgis.import("@arcgis/core/widgets/Popup/PopupViewModel.js");- Inheritance:
- PopupViewModel→
FeaturesViewModel→ Accessor
- Since
- ArcGIS Maps SDK for JavaScript 4.0
Provides the logic for the Popup widget and component, which allows users to view content from feature attributes. Popups enhance web applications by providing users with a simple way to interact with and view attributes in a layer. They play an important role in relaying information to the user, which improves the storytelling capabilities of the application.
- See also
Popup widget - Deprecated since 5.0. Use the Popup component instead.
Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
actions
- Type
- Collection<PopupAction>
Collection of action or action toggle objects.
Each action may be executed by clicking the icon or image symbolizing them.
By default, every popup and Features widget has 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 includeDefaultActions to false, or by setting the
PopupTemplate.overwriteActions property to true in a PopupTemplate.
The order of each action is the order in which they appear in the actions Collection.
The @trigger-action event fires each time an action is clicked.
Actions are defined with the properties listed in the ActionButton or ActionToggle class.
Example
// Defines an action button to zoom out from the selected featureconst 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.view.popup.viewModel.actions.push(zoomOutAction);
// Adds the custom action to the Features widgetfeaturesWidget.viewModel.actions.push(zoomOutAction); active
- Type
- boolean
Indicates if the view model is active when it is visible and is not waiting for results.
- See also
activeFeature
- Since
- ArcGIS Maps SDK for JavaScript 4.32
The highlighted feature on the map that is either hovered over or in focus within the feature menu.
allActions
- Type
- Collection<PopupAction>
A collection of actions or action toggles.
autoCloseEnabled
- Type
- boolean
- Default value
- false
browseClusterEnabled
- Type
- boolean
Indicates if the "Browse features" experience is active in a
cluster popup. This value becomes
true when the user enables feature browsing with the "Browse features" cluster
action button.
It becomes false when the view scale changes, when the widget is closed, or when the user disables
the "Browse features" action. This should only be set programmatically when the
selectedFeature is
an aggregate graphic and represents a cluster.
- Default value
- false
Example
// open the browse features experience for a cluster graphicfeaturesWidget.viewModel.browseClusterEnabled = featuresWidget.viewModel.selectedFeature?.isAggregate;
view.popup.viewModel.browseClusterEnabled = view.popup.viewModel.selectedFeature?.isAggregate; content
- Type
- string | HTMLElement | Widget | null | undefined
The information to display. When this property is set, this content may only be 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.
- See also
Example
// This sets generic instructions in the popup that will always be displayed// unless it is overridden by a PopupTemplate.// This can be set on the Features widget view modelfeaturesWidget.viewModel.content = "Click a feature on the map to view its attributes";
// Or set on the Popup widget view model.view.popup.viewModel.content = "Click a feature on the map to view its attributes"; defaultActions
- Type
- Collection<PopupAction>
A read-only property that specifies a Collection of action buttons and/or toggles. By default, there is a "Zoom to" action that allows users to zoom to the selected feature.
In order to disable any default actions, it is necessary to set includeDefaultActions to false.
defaultPopupTemplateEnabled
- Type
- boolean
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, and
ImageryLayer).
- Default value
- false
featureCount
- Type
- number
The number of selected features available.
- Default value
- 0
featureMenuOpen
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.32
This property enables showing the 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.
- Default value
- false
featureMenuTitle
The title to display on the widget while viewing the feature menu.
featurePage
- Since
- ArcGIS Maps SDK for JavaScript 4.32
The current page number in the feature browsing menu. If the feature menu is not open, this value is null.
This value is dependent on the featuresPerPage.
features
- Type
- Graphic[]
An array of features. 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 properties
are 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 there are no features associated with the view model.
Example
// 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}"});// Create an array of graphics and set this to the features property. The content and title of// 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];// This value can be set on the popup or Features view model.view.popup.viewModel.features = graphics;featuresWidget.viewModel.features = graphics; featuresPerPage
- Type
- number
The number of features to fetch at one time.
- Default value
- 20
featureViewModelAbilities
- Type
- FeatureViewModelAbilities | null | undefined
Defines the specific Abilities that can be used when querying and displaying content.
featureViewModels
- Type
- FeatureViewModel[]
An array of feature view model(s).
goToOverride
- Type
- GoToOverride | null | undefined
- Since
- ArcGIS Maps SDK for JavaScript 4.8
This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.
- See also
Example
// The following snippet uses Search but can be applied to any// widgets that support the goToOverride property.search.goToOverride = function(view, goToParams) { goToParams.options = { duration: updatedDuration }; return view.goTo(goToParams.target, goToParams.options);}; highlightEnabled
- Type
- boolean
Highlight the selected feature using one of the HighlightOptions defined in the view's View.highlights collection.
- Default value
- true
includeDefaultActions
- Type
- boolean
Indicates whether or not to include defaultActions.
In order to disable any default actions, it is necessary to set includeDefaultActions to false.
- Default value
- true
Example
// Removes the default actionsviewModel.includeDefaultActions = false; initialDisplayMode
- Since
- ArcGIS Maps SDK for JavaScript 4.32
Indicates whether to initially display a list of features, or the content for one feature.
- Default value
- "feature"
location
Geometry used to show the location of the feature. This is automatically set when selecting a feature. If displaying content not related to features in the map, such as the results from a task, then you must set this property before making the widget visible to the user.
- See also
Examples
// Sets the location of the popup to the center of the viewview.popup.viewModel.location = view.center;// Displays the popupview.popup.visible = true;// Display a popup when and where the user clicks the view.reactiveUtils.on(()=>view, "click", ({ mapPoint })=>{ view.popup.viewModel.location = mapPoint; view.popup.visible = true;}); map
- Since
- ArcGIS Maps SDK for JavaScript 4.30
A map is required when the input features have a popupTemplate that contains Arcade expressions in ExpressionInfo or ExpressionContent that may use the $map profile variable to access data from layers within a map. Without a map, expressions that use $map will throw an error.
Alternatively, the view property can be used to provide the map instance for this property.
Example
// The building footprints represent the buildings that intersect a clicked parcellet buildingFootprints = Intersects($feature, FeatureSetByName($map, "Building Footprints")); pendingPromisesCount
- Type
- number
The number of promises remaining to be resolved.
- See also
- Default value
- 0
promiseCount
- Type
- number
The number of selected promises available.
- Default value
- 0
promises
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.
screenLocation
- Type
- ScreenPoint | null | undefined
- Since
- ArcGIS Maps SDK for JavaScript 4.32
The screen location of the selected feature.
screenLocationEnabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.32
Determines whether screen point tracking is active for positioning.
- Default value
- false
selectedClusterBoundaryFeature
- Type
- Graphic
The graphic used to represent the cluster extent when the Browse features action
is active. Only applies when a PopupTemplate is set on
a FeatureReductionCluster instance.
selectedFeature
The selected feature accessed. The content is determined based on the PopupTemplate assigned to this feature.
selectedFeatureViewModel
- Type
- FeatureViewModel
- Since
- ArcGIS Maps SDK for JavaScript 4.32
The view model of the selected feature.
spatialReference
- Type
- SpatialReference | null | undefined
- Since
- ArcGIS Maps SDK for JavaScript 4.30
The spatial reference used for Arcade operations. This property should be set if Arcade expressions are executed that contain geometry functions.
Alternatively, the view property can be used to provide the spatial reference instance for this property.
state
- Type
- State
The view model's state.
- Default value
- "disabled"
timeZone
- Type
- TimeZone
- Since
- ArcGIS Maps SDK for JavaScript 4.30
Dates and times will be displayed in this time zone. By default this time zone is
inherited from MapView.timeZone if the view property is set. When a MapView is not associated with the widget view model,
then the property will fallback to the system time zone.
Possible Values
| Value | Description |
|---|---|
| system | Dates and times will be displayed in the timezone of the device or browser. |
| unknown | Dates and time are not adjusted for any timezone. |
| Specified IANA timezone | Dates and times will be displayed in the specified IANA time zone. See wikipedia - List of tz database time zones. |
title
The title of the widget. This can be set to any string value 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.
Example
// This title will display in the popup unless a selected feature's// PopupTemplate overrides it.view.popup.viewModel.title = "Population by zip codes in Southern California"; updateLocationEnabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.32
Indicates whether to update the location when the selectedFeatureIndex changes.
- Default value
- false
view
- Type
- MapViewOrSceneView | null | undefined
A reference to the MapView or SceneView.
The FeaturesViewModel requires a view if the user expects it to display content in any of the following situations:
- The features have a popupTemplate containing Arcade expressions in ExpressionInfo or ExpressionContent that may use geometry functions or reference the
$mapprofile variable (i.e. access data from layers within a map). - Content is displayed from the popup template of an aggregate feature (i.e. a cluster or bin).
- Values from
dateandtimestamp-offsetfields should respect the view's time zone. - When using the fetchFeatures() method or the
fetchFeaturesoption in the open() method.
visible
- Type
- boolean
Indicates whether the widget is visible. This property is true when the widget is querying for results, even if it is not open in the view.
Use the active property to check if the widget is visible and is not waiting for results.
- See also
- Default value
- false
waitingForContents
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.32
Indicates whether the widget is waiting for content to be resolved.
waitingForResult
- Type
- boolean
- Default value
- false
zoomFactor
- Type
- number
- Since
- ArcGIS Maps SDK for JavaScript 4.34
Number of levels of detail (LOD) to zoom in on the selected feature.
- Default value
- 4
Example
// Restricts the zooming to two LODS when the zoom in action is clicked.features.viewModel.zoomFactor = 2;Methods
| Method | Signature | Class |
|---|---|---|
clear inherited | clear(): void | |
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
fetchFeatures inherited | fetchFeatures(screenPoint: ScreenPoint | null | undefined, options?: FetchFeaturesOptions): Promise<FetchPopupFeaturesResult> | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
next inherited | next(): FeaturesViewModel | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
open inherited | open(options?: PopupOpenOptions): void | |
previous inherited | previous(): FeaturesViewModel | |
triggerAction inherited | triggerAction(actionIndex: number): void | |
zoomTo inherited | zoomTo(params: GoToParameters): Promise<void> |
emit
- Signature
-
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
- Type parameters
- <Type extends EventNames<this>>
- Since
- ArcGIS Maps SDK for JavaScript 4.5
Emits an event on the instance. This method should only be used when creating subclasses of this class.
fetchFeatures
- Signature
-
fetchFeatures (screenPoint: ScreenPoint | null | undefined, options?: FetchFeaturesOptions): Promise<FetchPopupFeaturesResult>
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 FeatureLayer.popupEnabled. These features can then be used within a custom Popup, Features, or Feature widget experience. One example could be a custom side panel that displays feature-specific information based on an end user's click location. This method allows a developer the ability to control how the input location is handled, and then subsequently, what to do with the results.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| screenPoint | ScreenPoint | null | undefined | An object representing a point on the screen. This point can be in either the ScreenPoint or ScreenPoint. | |
| options | The options
to pass into the | |
- Returns
- Promise<FetchPopupFeaturesResult>
Resolves with the selected
hitTestlocation. In addition, it also returns an array of graphics if thehitTestis performed directly on the View, a single Promise containing an array of all resulting graphics, or an array of objects containing this array of resulting graphics in addition to its associated LayerView.Most commonly if accessing all features, use the single promise returned in the result's allGraphicsPromise and call
.then()as seen in the example snippet.
Example
// Get view's click eventreactiveUtils.on(()=>view, "click", (event) => { // Call fetchFeatures and pass in the click event screenPoint viewModel.fetchFeatures(event.screenPoint).then((response) => { // Access the response from fetchFeatures response.allGraphicsPromise.then((graphics) => { // Do something with the returned graphic from fetchFeatures such as setting this to the // Features widget graphic property. featureWidget.graphic = graphics[0]; }); });}); hasEventListener
- Signature
-
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
- Type parameters
- <Type extends EventNames<this>>
Indicates whether there is an event listener on the instance that matches the provided event name.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | The name of the event. | |
- Returns
- boolean
Returns true if the class supports the input event.
next
- Signature
-
next (): FeaturesViewModel
Selects the feature at the next index in relation to the selected feature.
- See also
- Returns
- FeaturesViewModel
Returns an instance of the popup's view model.
on
- Signature
-
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
- Type parameters
- <Type extends EventNames<this>>
Registers an event handler on the instance. Call this method to hook an event with a listener.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | An event or an array of events to listen for. | |
| listener | EventedCallback<this["@eventTypes"][Type]> | The function to call when the event fires. | |
- Returns
- ResourceHandle
Returns an event handler with a
remove()method that should be called to stop listening for the event(s).Property Type Description remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){ // event is the event handle returned after the event fires. console.log(event.mapPoint);}); open
- Signature
-
open (options?: PopupOpenOptions): void
Opens the widget at the given location with content defined either explicitly with content
or driven from the PopupTemplate of input features. This method sets the
visible property to true. Users can alternatively set the visible property to true.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| options | Defines the location and content of the popup when opened. | |
- Returns
- void
Examples
// Manually opens the corresponding widget.reactiveUtils.on(()=>view, "click", (event)=>{ viewModel.open({ location: event.mapPoint, title: "You clicked here", content: "This is a point of interest" });});// Displays the content for the selected feature if a popupTemplate is defined at the view // click event location. reactiveUtils.on(()=>view, "click", (event)=>{ view.popup.viewModel.open({ location: event.mapPoint, fetchFeatures: true }); });// Opens the corresponding widget with the specified title and content and updates// the location of the popup based on the selected feature's geometry.view.popup.viewModel.open({ title: "You clicked here", content: "This is a point of interest", updateLocationEnabled: true});// Opens the Features widget with the specified graphics.// This will only work if the array of graphics have a popup template defined.featuresWidget.viewModel.open({ features: graphics}); previous
- Signature
-
previous (): FeaturesViewModel
Selects the feature at the previous index in relation to the selected feature.
- See also
- Returns
- FeaturesViewModel
Returns an instance of the popup's view model.
triggerAction
- Signature
-
triggerAction (actionIndex: number): void
Triggers the @trigger-action event and executes the action at the specified index in the actions array.
zoomTo
- Signature
-
zoomTo (params: GoToParameters): Promise<void>
- Since
- ArcGIS Maps SDK for JavaScript 4.32
Sets the view to a given target. If goToOverride is set, goToOverride() will be called with the current view and specified params.
Otherwise, the view will be set using the provided params.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| params | The parameters to pass to the | |
Events
| Name | Type |
|---|---|
trigger-action inherited |
trigger-action
trigger-action: CustomEvent<ActionEvent> Fires after the user clicks on an action or action toggle in the action bar. This event may be used to define a custom function to execute when particular actions are clicked. See the example below for details of how this works.
Examples
featuresWidget.open({ location: event.mapPoint, fetchFeatures: true, featureMenuOpen: 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 className: "esri-icon-zoom-out-magnifying-glass" }, { title: "Delete Feature", id: "delete-feature-action", icon: "trash" }]});
// Fires each time an action is clickedreactiveUtils.on(()=> featuresWidget, "trigger-action", (event)=>{ // If the zoom-out action is clicked, execute the following code if(event.action.id === "zoom-out"){ // Zoom out two levels (LODs) view.goTo({ center: view.center, zoom: view.zoom - 2 }); }});// Defines an action button to zoom out from the selected featureconst 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.view.popup.actions.push(zoomOutAction);
// This event fires for each click on any actionreactiveUtils.on(()=>view.popup?.viewModel, "trigger-action", (event)=>{ // If the zoom-out action is clicked, fire the zoomOut() function if(event.action.id === "zoom-out"){ // in this case the view zooms out two LODs on each click view.goTo({ center: view.center, zoom: view.zoom - 2 }); }});// Defines an action button to zoom out from the selected featureconst 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.view.popup.actions.push(zoomOutAction);
// This event fires for each click on any actionreactiveUtils.on(()=>view.popup?.popupViewModel, "trigger-action", (event)=>{ // If the zoom-out action is clicked, fire the zoomOut() function if(event.action.id === "zoom-out"){ // in this case the view zooms out two LODs on each click view.goTo({ center: view.center, zoom: view.zoom - 2 }); }});