arcgis-features | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-features";

Inheritance:: ArcgisFeatures→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Features component allows users to view a feature's popupTemplate content such as attributes, actions, related records, etc., without having to be tied to an arcgis-map or arcgis-scene component. This component looks and behaves similarly to the arcgis-popup component, however unlike Popup, the Features component can be placed outside of the map or scene component. For example, when features are selected in the arcgis-map, the arcgis-popup opens within the map whether it is docked or anchored to the selected feature. With the Features component, the same information that Popup provides is shown in a separate container from the map, such as a HTML div within a Calcite Design System Shell Panel.

If multiple features are passed into the Features component, the component provides buttons to page though the features and a feature menu that allows the list of features to be displayed so the user can choose which feature content to display in the component. The component also respects feature reduction PopupTemplates for binning and clustering.

The Features component should be used if needing to use the Popup functionality outside of the map or scene component. If wanting to show a single feature's content without actions, related records, clustering configuration, etc., then use the arcgis-feature component.

See also

PopupTemplate

Demo

Properties

Property	Attribute	Type
`actions`		`Collection<PopupAction>`
`active` readonly		`boolean`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`chartAnimationDisabled`	`chart-animation-disabled`	`boolean`
`collapsed`	`collapsed`	`boolean`
`content`	`content`	`string \| HTMLElement \| Widget<any> \| null \| undefined`
`defaultPopupTemplateEnabled`	`default-popup-template-enabled`	`boolean`
`featureCount`	`feature-count`	`number`
`featureMenuOpen`	`feature-menu-open`	`boolean`
`featureMenuTitle`	`feature-menu-title`	`string \| null \| undefined`
`featureNavigationTop`	`feature-navigation-top`	`boolean`
`features`		`Array<Graphic>`
`featuresPerPage`	`features-per-page`	`number`
`featureViewModelAbilities`		`Abilities \| null \| undefined`
`goToOverride`		`GoToOverride \| null \| undefined`
`headerActions`		`Collection<ActionButton \| ActionToggle>`
`heading`	`heading`	`string \| null \| undefined`
`headingLevel`	`heading-level`	`HeadingLevel`
`hideActionBar`	`hide-action-bar`	`boolean`
`hideAttachmentsContent`	`hide-attachments-content`	`boolean`
`hideCloseButton`	`hide-close-button`	`boolean`
`hideContent`	`hide-content`	`boolean`
`hideCustomContent`	`hide-custom-content`	`boolean`
`hideExpressionContent`	`hide-expression-content`	`boolean`
`hideFeatureListLayerTitle`	`hide-feature-list-layer-title`	`boolean`
`hideFeatureMenuHeading`	`hide-feature-menu-heading`	`boolean`
`hideFeatureNavigation`	`hide-feature-navigation`	`boolean`
`hideFieldsContent`	`hide-fields-content`	`boolean`
`hideHeading`	`hide-heading`	`boolean`
`hideLastEditedInfo`	`hide-last-edited-info`	`boolean`
`hideMediaContent`	`hide-media-content`	`boolean`
`hideRelationshipContent`	`hide-relationship-content`	`boolean`
`hideSpinner`	`hide-spinner`	`boolean`
`hideTextContent`	`hide-text-content`	`boolean`
`hideUtilityNetworkContent`	`hide-utility-network-content`	`boolean`
`highlightDisabled`	`highlight-disabled`	`boolean`
`icon`	`icon`	`IconName \| undefined`
`includeDefaultActionsDisabled`	`include-default-actions-disabled`	`boolean`
`initialDisplayMode`	`initial-display-mode`	`InitialDisplayOptions`
`label`	`label`	`string \| undefined`
`map`		`Map \| null \| undefined`
`messageOverrides`		`Record<string, unknown> \| undefined`
`open`	`open`	`boolean`
`promises`		`Array<Promise<Array<Graphic>>>`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`selectedDrillInFeature` readonly		`Graphic \| null \| undefined`
`selectedFeature` readonly		`Graphic \| null`
`selectedFeatureComponent` readonly		`ArcgisFeature \| null`
`selectedFeatureIndex`	`selected-feature-index`	`number`
`showCollapseButton`	`show-collapse-button`	`boolean`
`spatialReference`		`SpatialReference \| null \| undefined`
`state` readonly		`State`
`timeZone`	`time-zone`	`string`
`updateLocationEnabled`	`update-location-enabled`	`boolean`
`view`		`MapViewOrSceneView \| null \| undefined`
`viewModel`		`FeaturesViewModel`

actions

Property

Type: Collection<PopupAction>

A collection of action button or action toggle objects. Each action may be executed by clicking the icon or image symbolizing them. There is a default Zoom To action styled with a magnifying glass icon to zoom in four LODs and center the map on the selected feature. This default action can be removed 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

active

readonly Property

Type: boolean

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

Default value: false

autoDestroyDisabled

Property

Type: boolean

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

chartAnimationDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Disables chart animation within the component.

Attribute: chart-animation-disabled
Default value: false

collapsed

Property

Type: boolean

Indicates whether the component displays its content. If true, only the header displays. This property is only honored if showCollapseButton is true.

Attribute: collapsed
Default value: false

content

Property

Type: string | HTMLElement | Widget<any> | null | undefined

The content of the component. When set directly on the component, 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.

Attribute: content

Example

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

defaultPopupTemplateEnabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

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.

Note: 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

featureCount

Property

Type: number

Since: ArcGIS Maps SDK for JavaScript 4.34

The number of features available in the component.

Attribute: feature-count

featureMenuOpen

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

This property enables multiple features in the component to display in a list rather than displaying the first selected feature. 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

featureMenuTitle

Property

Type: string | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

Sets the title to display on the component while viewing the feature menu.

Attribute: feature-menu-title

featureNavigationTop

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

Indicates whether the feature navigation arrows are displayed at the top of the component. By default, the navigation arrows are displayed at the bottom of the component.

Attribute: feature-navigation-top
Default value: false

features

Property

Type: Array<Graphic>

An array of features associated with the component. 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 heading of the component 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 component is set based on the value of the selectedFeature).

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

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}"
});
// Set the graphics as an array to the popup instance. The content and title of
// the component 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];
component.features = graphics;

featuresPerPage

Property

Type: number

The number of features to fetch at one time.

Attribute: features-per-page
Default value: 20

featureViewModelAbilities

Property

Type: Abilities | null | undefined

Defines the specific abilities that can be used when querying and displaying content.

goToOverride

Property

Type: GoToOverride | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.33

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

Example

component.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

headerActions

Property

Type: Collection<ActionButton | ActionToggle>

The actions that are displayed in the header of the component.

heading

Property

Type: string | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

The title of the Features component. This can be set to any string value no matter the features that are selected. If the selectedFeature has a PopupTemplate, then the title set in the corresponding template is used here.

See also

headingLevel

Attribute: heading

Example

// This title will display in the component unless a selected feature's
// PopupTemplate overrides it.
featuresComponent.title = "Population by zip codes in Southern California";

headingLevel

Property

Type: HeadingLevel

Indicates the heading level to use for the heading of the component. 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.

Attribute: heading-level
Default value: 2

hideActionBar

Property

Type: boolean

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

Attribute: hide-action-bar
Default value: false

hideAttachmentsContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show attachments content within the component.

Attribute: hide-attachments-content
Default value: false

hideCloseButton

Property

Type: boolean

Indicates whether to hide the close button in the component.

Attribute: hide-close-button
Default value: false

hideContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show content within the component.

Attribute: hide-content
Default value: false

hideCustomContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show custom content within the component.

Attribute: hide-custom-content
Default value: false

hideExpressionContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show expression content within the component.

Attribute: hide-expression-content
Default value: false

hideFeatureListLayerTitle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

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

Attribute: hide-feature-list-layer-title
Default value: false

hideFeatureMenuHeading

Property

Type: boolean

Indicates whether to hide the feature menu heading and description in the component's feature menu list.

Attribute: hide-feature-menu-heading
Default value: false

hideFeatureNavigation

Property

Type: boolean

Indicates whether to hide the feature navigation in the component. This allows the user to scroll through various features using pagination arrows.

Attribute: hide-feature-navigation
Default value: false

hideFieldsContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show fields content within the component.

Attribute: hide-fields-content
Default value: false

hideHeading

Property

Type: boolean

Indicates whether to hide the heading in the component.

Attribute: hide-heading
Default value: false

hideLastEditedInfo

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show the last edited info within the component.

Attribute: hide-last-edited-info
Default value: false

hideMediaContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show media content within the component.

Attribute: hide-media-content
Default value: false

hideRelationshipContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show relationship content within the component.

Attribute: hide-relationship-content
Default value: false

hideSpinner

Property

Type: boolean

Indicates whether to hide the spinner in the component.

Attribute: hide-spinner
Default value: false

hideTextContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show text content within the component.

Attribute: hide-text-content
Default value: false

hideUtilityNetworkContent

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

This property provides the ability to hide or show utility network content within the component.

Attribute: hide-utility-network-content
Default value: false

highlightDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

Indicates whether to highlight the selectedFeature in the associated arcgis-map or arcgis-scene component.

Attribute: highlight-disabled
Default value: false

icon

Property

Type: IconName | undefined

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon

includeDefaultActionsDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

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

initialDisplayMode

Property

Type: InitialDisplayOptions

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

Attribute: initial-display-mode
Default value: "feature"

label

Property

Type: string | undefined

The component's default label.

Attribute: label

map

Property

Type: Map | null | undefined

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.

See also

Default value: null

Example

// The building footprints represent the buildings that intersect a clicked parcel
let buildingFootprints = Intersects($feature, FeatureSetByName($map, "Building Footprints"));

messageOverrides

Property

Type: Record<string, unknown> | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

open

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

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

See also

Attribute: open
Default value: false

Example

// Listen for clicks on the view and open the component at the clicked location with custom content.
viewElement.addEventListener("arcgisViewClick", (event) => {
  const { mapPoint } = event.detail;
  component.location = mapPoint;
  component.heading = "You clicked here";
  component.content = "Latitude: " + mapPoint.latitude.toFixed(3) + ", Longitude: " + mapPoint.longitude.toFixed(3);
  component.open = true;
});

promises

Property

Type: Array<Promise<Array<Graphic>>>

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.

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

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

selectedDrillInFeature

readonly Property

Type: Graphic | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

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

selectedFeature

readonly Property

Type: Graphic | null

The selected feature accessed by the Features component. The content displayed in the component is determined based on the PopupTemplate assigned to this feature.

selectedFeatureComponent

readonly Property

Type: ArcgisFeature | null

Since: ArcGIS Maps SDK for JavaScript 4.34

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

selectedFeatureIndex

Property

Type: number

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

Attribute: selected-feature-index

showCollapseButton

Property

Type: boolean

Indicates whether to show the collapse button in the component.

Attribute: show-collapse-button
Default value: false

spatialReference

Property

Type: SpatialReference | null | undefined

The spatial reference used for Arcade operations. This property should be set if the Features component executes Arcade expressions that contain geometry functions.

Alternatively, the view property can be used to provide the spatial reference instance for this property.

See also

Default value: null

state

readonly Property

Type: State

The current state of the component.

Default value: "disabled"

timeZone

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 4.30

Dates and times displayed in the component will be displayed in this time zone. By default this time zone is inherited from arcgis-map.timeZone if the view property is set. When a MapView is not associated with the component then the property will fallback to the system time zone.

Possible Values

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.

Attribute: time-zone

updateLocationEnabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to update the location when the selectedFeatureIndex changes.

Attribute: update-location-enabled
Default value: false

view

Property

Type: MapViewOrSceneView | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

A reference to the MapView or SceneView. The Features component requires a view to be set if:

The features have a popupTemplate containing Arcade expressions in ExpressionInfo or ExpressionContent that may use geometry functions or reference the $map profile variable (i.e. access data from layers within a map). Alternatively, set the map property.
Content is displayed from the popup template of an aggregate feature (i.e. a cluster or bin).
Values from date and timestamp-offset fields should respect the view's time zone. Alternatively, set the timeZone property.
Using the fetchFeatures() method or the fetchFeatures option in the open method.
Using the Zoom to default action. If the view is not specified, set the includeDefaultActionsDisabled property to true to remove this default action.

viewModel

Property

Type: FeaturesViewModel

Since: ArcGIS Maps SDK for JavaScript 4.34

Methods

Method	Signature
`clear`	`clear(): Promise<void>`
`close`	`close(): Promise<void>`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`fetchFeatures`	`fetchFeatures(screenPoint?: ScreenPoint, options?: FetchFeaturesOptions): Promise<void>`
`next`	`next(): Promise<FeaturesViewModel>`
`previous`	`previous(): Promise<FeaturesViewModel>`
`setFocus`	`setFocus(): Promise<void>`
`triggerAction`	`triggerAction(action: ActionButton \| ActionToggle): Promise<void>`

clear

Method

Signature: clear (): Promise<void>

Removes promises, features, content, and heading from the Features component.

Returns: Promise<void>

close

Method

Signature: close (): Promise<void>

A convenience method to close the component.

Returns: Promise<void>

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisFeatures = document.querySelector("arcgis-features");
document.body.append(arcgisFeatures);
await arcgisFeatures.componentOnReady();
console.log("arcgis-features is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

fetchFeatures

Method

Signature: fetchFeatures (screenPoint?: ScreenPoint, options?: FetchFeaturesOptions): 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. This method allows a developer to control how the input location is handled. For example, you may want to fetch features on a click event or on a pointer-move event. This method automatically sets the location based on the input event's screen coordinates.

See also

open

Parameters

Parameter	Type	Description	Required
screenPoint	`ScreenPoint`
options	`FetchFeaturesOptions`

Returns: Promise<void>

Example

const viewElement = document.querySelector("arcgis-map");
// Get viewElement's click event
reactiveUtils.on(()=>viewElement, "arcgisViewClick", async (event)=>{
  // Call fetchFeatures on the component and pass in the click event detail
  await component.fetchFeatures(event.detail);
});
// Watch for changes to the features property and open the component when features are available.
reactiveUtils.watch(
  () => component.features,
  () => {
    component.open = component.features ? true : false;
  },
);

Method

Signature: next (): Promise<FeaturesViewModel>

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

See also

selectedFeatureIndex

Returns: Promise<FeaturesViewModel>

Method

Signature: previous (): Promise<FeaturesViewModel>

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

See also

selectedFeatureIndex

Returns: Promise<FeaturesViewModel>

setFocus

Method

Signature: setFocus (): Promise<void>

Since: ArcGIS Maps SDK for JavaScript 4.34

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

Returns: Promise<void>

triggerAction

Method

Signature: triggerAction (action: ActionButton | ActionToggle): Promise<void>

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

Parameters

Parameter	Type	Description	Required
action	`ActionButton \| ActionToggle`

Returns: Promise<void>

Events

Name	Type
`arcgisClose`	CustomEvent<void>
`arcgisPropertyChange`	CustomEvent<{ name: "active" \| "collapsed" \| "featureCount" \| "featureMenuOpen" \| "features" \| "promises" \| "selectedDrillInFeature" \| "selectedFeature" \| "selectedFeatureComponent" \| "selectedFeatureIndex" \| "state" \| "open"; }>
`arcgisReady`	CustomEvent<void>
`arcgisTriggerAction`	CustomEvent<ActionEvent>

arcgisClose

Event

arcgisClose: CustomEvent<void>

Emitted when the component's close button is clicked.

arcgisPropertyChange

Event

 arcgisPropertyChange: CustomEvent<{ name: "active" | "collapsed" | "featureCount" | "featureMenuOpen" | "features" | "promises" | "selectedDrillInFeature" | "selectedFeature" | "selectedFeatureComponent" | "selectedFeatureIndex" | "state" | "open"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

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

arcgisTriggerAction

Event

arcgisTriggerAction: CustomEvent<ActionEvent>

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

See also

Example

// Fires each time an action is clicked
reactiveUtils.on(()=> component, "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
    });
  }
});