Types
import type { PopupView } from "@arcgis/core/views/PopupView.js";
Subclasses
View2D, SceneView
Since
ArcGIS Maps SDK for JavaScript 4.27

Mixin for Views that provides popup functionality.

Properties

PropertyTypeClass
deprecated
deprecated
autocast deprecated Property
Type
Popup | null | undefined

A Popup object that displays general content or attributes from layers in the map.

By default, the popup property is an empty object that allows you to set the popup options. A Popup instance is automatically created and assigned to the view's popup when the user clicks on the view and popupEnabled is true, when the openPopup method is called, or when some widgets need the popup, such as Search. If popup is null, the popup instance will not be created.

See also
Examples
// Set the view's popup to a new Popup instance.
// The popup will show anytime a popup is called such as when selecting features or displaying a Search result.
view.popup = new Popup();
// Set the popup to a PopupOptions object with popup properties set such as the dock options.
// The popup will show anytime a popup is called.
view.popup = {
dockEnabled: true,
dockOptions: {
position: "top-left",
breakpoint: false
}
};
// Set the popup to null. This disables the popup so it will never show up.
view.popup = null;

popupEnabled

deprecated Property
Type
boolean

Controls whether the popup opens when users click on the view.

When true, a Popup instance is created and assigned to popup the first time the user clicks on the view, unless popup is null. The popup then processes the click event.

When false, the click event is ignored and popup is not created for features but will open for other scenarios that use a popup, such as displaying Search results.

See also
Default value
true
Example
// Disable the popup from automatically appearing and
// open the popup manually using a click event.
view.popupEnabled = false;
view.on("click", (event)=> {
view.openPopup({
// Set properties for the manually opened popup
...
});
});

Methods

MethodSignatureClass
deprecated
closePopup(): void
fetchPopupFeatures(hitTarget: ScreenPoint | ScreenRect, options?: FetchPopupFeaturesOptions): AsyncGenerator<Graphic>
deprecated
openPopup(options?: ViewPopupOpenOptions): Promise<void>

closePopup

deprecated Method
Signature
closePopup (): void

Closes the popup.

See also
Returns
void
Example
// Closes the popup if it's open
if(view.popup.visible){
view.closePopup();
}

fetchPopupFeatures

Method
Signature
fetchPopupFeatures (hitTarget: ScreenPoint | ScreenRect, options?: FetchPopupFeaturesOptions): AsyncGenerator<Graphic>
Since
ArcGIS Maps SDK for JavaScript 5.1

Use this method to query for features at a given screen location. These features come from origins (layers and sublayers) configured with a PopupTemplate and have its FeatureLayer.popupEnabled set.

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 to control how the input location is handled, and then subsequently, what to do with the results.

Using ScreenRect as the hit target is considered beta functionality.

Parameters

ParameterTypeDescriptionRequired
hitTarget
options
Returns
AsyncGenerator<Graphic>

An async generator of features ready to be displayed by the popup, with the attributes and geometry required by their popup template. Generator yields features as soon as they are available in the top to bottom order. Popup hit testing begins when this method is called, while resolving features from those hits remains deferred until the generator is consumed.

Examples
// Consume features from the generator as soon as they are available
view.on("click", async (event) => {
const screenPoint = { x: event.x, y: event.y };
const generator = view.fetchPopupFeatures(screenPoint, {
pointerType: event.pointerType
});
for await (const feature of generator) {
console.log(feature);
}
});
// Wait for all the features to be available
view.on("click", async (event) => {
const generator = view.fetchPopupFeatures({ x: event.x, y: event.y }, {
pointerType: event.pointerType
});
const features = await Array.fromAsync(generator);
console.log(`${features.length} available for popup`);
});
// Get the top most feature
view.on("click", async (event) => {
const controller = new AbortController();
const screenPoint = { x: event.x, y: event.y };
const generator = view.fetchPopupFeatures(screenPoint, {
pointerType: event.pointerType,
signal: controller.signal
});
const result = await generator.next();
const feature = result.done ? null : result.value;
// abort the pending iterations
controller.abort();
console.log(`top most feature`, feature);
});

openPopup

deprecated Method
Signature
openPopup (options?: ViewPopupOpenOptions): Promise<void>

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.

A Popup instance is created and assigned to popup the first time openPopup() is called, unless popup is null. The popup then processes the click event.

When calling this method, to prevent the popup from opening when clicking on the view, set popupEnabled to false to stop event propagation on the view.

The popup will only display if the view's size constraints in dockOptions are met or the location property is set to a geometry.

See also

Parameters

ParameterTypeDescriptionRequired
options

Defines the location and content of the popup when opened.

Returns
Promise<void>

Resolves when the popup is opened. Calling openPopup() or closePopup() again rejects the Promise.

Examples
// Opens a popup manually depending on where the user clicks with specified title and content.
view.on("click", (event)=>{
view.openPopup({
location: event.mapPoint,
title: "You clicked here",
content: "This is a point of interest"
});
});
// Opens popup at the location of the click event and displays
// content for the selected features if a popupTemplate is defined.
view.on("click", (event)=>{
view.openPopup({
location: event.mapPoint,
fetchFeatures: true
});
});
// Opens popup with the properties specified at the location of the click event
// and updates the popup location based on the selected feature's geometry.
view.openPopup({
title: "You clicked here",
content: "This is a point of interest",
location: event.mapPoint,
updateLocationEnabled: true
});
// Opens popup with the specified array of graphics and displays the
// features in a list (feature menu) at the location of the first graphic in the array.
view.openPopup({
features: graphics,
featureMenuOpen: true,
location: graphics[0].geometry
});

Type definitions

ViewPopupOpenOptions

Type definition
Supertypes
Pick<PopupOpenOptions‚ "actions" | "content" | "features" | "featureStream" | "fetchFeatures" | "location" | "promises" | "title" | "updateLocationEnabled" | "shouldFocus">

FetchPopupFeaturesOptions

Type definition
Since
ArcGIS Maps SDK for JavaScript 5.1

Options for the fetchPopupFeatures() method. See properties below for object specifications.

Supertypes
AbortOptions

defaultPopupTemplateEnabled

Property
Type
boolean | undefined

A default popup template is automatically used if no popupTemplate is defined for a feature's origin

diagnostics

Property
Type
FetchPopupFeaturesDiagnostics | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

Collects diagnostics about the execution of fetchPopupFeatures(). See FetchPopupFeaturesDiagnostics for details.

Example

Check whether all matching popup features were returned.

const diagnostics: FetchPopupFeaturesDiagnostics = {};
const screenPoint = { x: event.x, y: event.y };
const features = await Array.fromAsync(
view.fetchPopupFeatures(screenPoint, { diagnostics })
);
if (diagnostics.layerLimitExceeded?.size) {
console.warn(
"Some matching popup features were omitted.",
Array.from(diagnostics.layerLimitExceeded, (origin) => getGraphicOriginTitle(origin)),
);
}

hitTestResolver

Property
Type
PromiseWithResolvers<void> | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

A resolver that is settled when popup hit testing finishes.

Use this option to wait until hits are captured before changing view or layer state that could invalidate the hit results. The promise resolves after successful hit testing and rejects if hit testing fails. Feature resolution remains deferred until the generator returned by fetchPopupFeatures() is consumed.

Example

Wait for hit testing to finish before removing an existing highlight.

view.on("click", async (event) => {
const hitTestResolver = Promise.withResolvers<void>();
const screenPoint = { x: event.x, y: event.y };
const featureStream = view.fetchPopupFeatures(screenPoint, {
hitTestResolver,
pointerType: event.pointerType
});
await hitTestResolver.promise;
currentHighlight?.remove();
for await (const feature of featureStream) {
console.log(feature);
}
});

pointerType

Property
Type
PointerType | undefined

The type of pointer coming from the input event. It influences the tolerance when querying for features on services. A touch pointer uses a larger tolerance than mouse or pen.

FetchPopupFeaturesDiagnostics

Type definition
Since
ArcGIS Maps SDK for JavaScript 5.2

Diagnostics collected while fetching popup features.

fetchPopupFeatures() updates this caller-provided object as its async generator is consumed.

See also

layerLimitExceeded

Property
Type
Set<GraphicOrigin> | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

Graphic origins whose layers could not process all matching features because their number exceeded the maximum the layer could process. For each origin, features up to that maximum can be returned, but features beyond it are not returned. The set is created the first time this maximum is exceeded.

Applications can use this information to tell users that results were omitted, log the condition, or ask users to narrow the search area.

Example

Check whether all matching popup features were returned.

const diagnostics: FetchPopupFeaturesDiagnostics = {};
const features = await Array.fromAsync(
view.fetchPopupFeatures({ x: event.x, y: event.y }, { diagnostics })
);
if (diagnostics.layerLimitExceeded?.size) {
console.warn(
"Some matching popup features were omitted.",
Array.from(diagnostics.layerLimitExceeded, (origin) => getGraphicOriginTitle(origin)),
);
}