Breaking changes

A comprehensive guide to all breaking changes for the ArcGIS Maps SDK for JavaScript, ordered by release version. This guide is helpful for people upgrading versions of the API in their app(s). Scroll down to find the current version of the API in use, then follow the changes up to the latest version, and make the relevant updates.

To see all the latest features and advancements, please refer to the Release Notes. To see all the added features and advancements from all versions, please refer to the Previous Versions Release Notes section.


  • At version 4.29, only WebGL2-enabled browsers are supported for both 2D and 3D. See the System Requirements for more information.

  • For local builds, using Webpack versions prior to 5.84.0 is not recommended at 4.29. This is related to bug fixes in Webpack.

  • The hitTest() method on the MapView no longer includes layerId and layerIndex in the attributes of a returned graphic for VectorTileLayer. To obtain this information, use the graphic's origin property instead. See the VectorTileLayer hitTest section for more info.

  • The layer property of a graphic returned in the hit test result for VectorTileLayer is now null. Use the origin.layer property to access which VectorTileLayer the graphic originates from.

  • The @arcgis/common-components (beta) package was removed, which included the arcgis-api-key and arcgis-identity components.

  • At version 4.29, ListItemPanels do not include any padding.

  • FeatureLayer can no longer be labelled with labelExpression, which is documented as only working with MapImageLayer. Use labelExpressionInfo instead.

  • The WFSLayer now uses pagination when fetching features from the service, meaning that multiple requests will be sent to retrieve features instead of just one. To match the previous behavior, set maxPageCount: 1 and increase the value of maxRecordCount.

  • The Editor's view model no longer creates a single instance of FeatureFormViewModel and SketchViewModel. Prior to this release, if given an instance of EditorViewModel, its featureFormViewModel and sketchViewModel properties always referred to the same single instance of their respective view model class for the entirety of the EditorViewModel lifetime. This meant that certain operations using these view models, could run once and remain effective for all subsequent editing workflows, (e.g. setting properties or installing event listeners on them). Beginning with version 4.29, new instances of FeatureFormViewModel and SketchViewModel are used for each editing workflow. When there isn't an active edit workflow, the FeatureFormViewModel and SketchViewModel properties are null. When an editing workflow begins, these properties will have values, but any changes or event handlers made to them are only applicable for the duration of that workflow.

  • The MeshGeoreferencedRelativeVertexSpace has been removed. Use MeshGeoreferencedVertexSpace with an origin instead. If no origin is specified, the georeferenced vertex space will be considered absolute.

  • Meshes created via create functions, such as createSphere, are now always created with a relative vertex space where mesh coordinates will be offsets to the location at which the mesh is created. Before, mesh coordinates would always be absolute. If the vertex space type is not provided as an option to the create function, then the vertex space is chosen based on the spatial reference. If it is geographic or WebMercator, MeshLocalVertexSpace is used and MeshGeoreferencedVertexSpace otherwise.

  • Mesh centerAt will now center meshes with respect to the origin of the vertex space of the mesh. Before, creating a sphere using createSphere at a location, followed by a call to centerAt with the same location as an argument, would move the sphere such that the sphere center aligns with the location. Now calling centerAt with the same location at which the mesh was created will not have any effect. Use offset or adjust the centerAt location by mesh.extent.height/2.

  • The FetchPopupFeaturesResult type definition in the Popup class had the following properties removed from the API at this release:


The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
Editor.useDeprecatedCreateWorkflowNo longer applicable4.23
FeatureTable.clearHighlights()call removeAll from FeatureTable.highlightIds4.25
FeatureTableViewModel.clearHighlights()call removeAll from FeatureTableViewModel.highlightIds4.25
Locate.useHeadingEnabledNo longer applicable4.27


Removal of watchUtils

The watchUtils class has been deprecated since version 4.24 and has been removed from the API at this release. This is a breaking change and applications will need to use reactiveUtils instead, which provides significantly improved utilities and convenience functions for watching properties inherited from Accessor. Check out the Why you should be using reactiveUtils instead of watchUtils blog for more details on how to migrate from watchUtils to reactiveUtils.

TypeScript breaking changes

  • The @types/arcgis-js-api package was deprecated in NPM at 4.28. This package was used in AMD-based applications. Download the latest definition files from the jsapi-resources archive, or NPM install arcgis-js-api. These changes do not affect applications using ES modules with @arcgis/core.

  • IPromise TypeScript definition was removed at 4.28. Use native Promise instead.

  • All instances of *Constructor TypeScript definitions were removed at 4.28. Update usage of __esri.ModuleConstructor to typeof __esri.Module, or import the module from typings and change the type assignment to typeof Module, for example:

    Use dark colors for code blocksCopy
    // Type definitions at 4.27 and earlier
    type IEsriDeps = [
    // Type definitions at 4.28 and later
    type IEsriDeps = [
      typeof __esri.Map,
      typeof __esri.MapView

Additional breaking changes

  • Authenticated users that are layer owners, administrators or users with full editing privileges will have their elevated user privileges applied in regards to editing behavior and data access. This mimic the behavior available in Map Viewer. To opt out, set esriConfig.userPrivilegesApplied to false.
  • Legacy basemaps: The legacy national-geographic named basemap was removed at 4.28. Four of the other legacy basemaps have been redefined to their vector equivalents because they were based on outdated services that are in Mature Support: topo, streets, gray and dark-gray.
  • The auto and authorization-code values for OAuthInfo.flowType no longer check if the popup property is set to true or false. This change affects applications that use the auto flowType and set the popup property to true. The callback page being used needs to be updated to support two-factor authentication. To aid in this, the default oauth-callback.html has been updated to allow for the two-step approach and will still work if using the one-step flow.
  • The default format for date fields is now short-date-short-time rather than long-month-day-year in the Popup, Features, or Feature widgets. For example, a date that may have previously appeared as December 30, 1997 will now appear as 12/30/1997 6:00 PM.
  • The default value of VoxelLayer.popupEnabled changed from true to false.
  • The MapView.goTo and MapView.toScreen default behavior has been changed to automatically be normalized based on the center of the view. Set pickClosestTarget in the GoToOptions2D or the ToScreenOptions2D to false to disable this behavior.
  • The maxInlineActions property on the Popup widget has been removed due to the widget being refactored to utilize Calcite components.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
watchUtilsUse reactiveUtils instead4.24
FeatureTable.fieldConfigs[]Set the field columns using the FeatureTable's tableTemplate property. This provides access to the columnTemplates.4.24
FeatureTableViewModel.fieldConfigs[]Set the field columns using the FeatureTable's tableTemplate property. This provides access to the columnTemplates.4.24
FieldColumnConfigUse FieldColumnTemplate instead4.23
FieldGroupUse FieldElement instead4.23
FieldGroupConfigUse GroupElement if working with the FeatureForm widget or GroupColumnTemplate if working with the FeatureTable widget.4.23
UtilityNetwork.rulesTableIdUse UtilityNetwork.networkSystemLayers.rulesTableId instead4.25
UtilityNetwork.rulesTableUrlUse UtilityNetwork.networkSystemLayers.rulesTableUrl instead4.25
UtilityNetwork.subnetworksTableIdUse UtilityNetwork.networkSystemLayers.subnetworksTableId instead4.25
UtilityNetwork.subnetworksTableUrlUse UtilityNetwork.networkSystemLayers.subnetworksTableUrl instead4.25


  • The Popup widget loading is deferred until the view is ready and finished updating, and will only be loaded if View.popupEnabled is set to true (which is the default), when View.openPopup() is called, or when some widgets need the popup, such as Search. In most cases, applications will not need to be updated and will continue to work. However, if attempting to access the view.popup property before it is instantiated, some issues may occur. See Loading the Popup for details on how to update your apps to take advantage of these performance improvements. Alternatively, you can simply create a new instance of the Popup when instantiating the View, as shown in the code snippet below. Note: this will not take advantage of the deferred loading.
    Use dark colors for code blocksCopy
    // Create a new MapView
    const view = new MapView({
      // set the popup property to a new instance of Popup
      popup: new Popup(...)
  • Compatibility with implementations that don't support async/await at runtime, within AMD modules, has been removed at 4.27. For example, some SDK applications using Angular with esri-loader may experience runtime errors, and will need to migrate from AMD modules to using @arcgis/core ES modules.
  • The old workflow of creating a Directions widget without a RouteLayer was deprecated at version 4.24 and is removed at 4.27. Directions widget must be created with a RouteLayer, like in the Directions widget sample.
  • Properties SunLighting.ambientOcclusionEnabled and SunLighting.waterReflectionEnabled have been deprecated with version 4.27 and have no effect. Ambient occlusion and reflections are now automatically controlled by the new adaptive rendering behavior.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
Directions.routeServiceUrlurl from Directions.layer4.24
Directions.routeSymboldirectionLines from Directions.layer4.24
Directions.stopSymbolsRouteStopSymbols from Directions.layer4.24
DirectionsViewModel.routeServiceUrlurl from DirectionsViewModel.layer4.24
DirectionsViewModel.routeSymboldirectionLines from DirectionsViewModel.layer4.24
DirectionsViewModel.stopsstops from DirectionsViewModel.layer4.24
DirectionsViewModel.stopSymbolsRouteStopSymbols from DirectionsViewModel.layer4.24


  • ImageryTileLayer's default title is now created from its URL like other layers instead of the name property from the service's root resource.
  • Setting Editor.layerInfos updateEnabled to false will not disable the ability to delete features. Prior to this release, setting updateEnabled to false would prevent both updates and deletes on a feature. Now if deletes are needed, it is necessary to also set deleteEnabled to true.
  • The default value of VoxelIsosurface.colorLocked changed from true to false.
  • The Editor widget's UI has been slightly updated to show snapping settings using an accordion component rather than a popover.
  • The globalIdsFilter property of GraphSearchStreaming was replaced with idsFilter.
  • The networkService.fetchServiceDescription() method now returns an object with a defaultTravelMode property of type TravelMode instead of type string.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated

Knowledge Graph beta changes

The knowledgeGraphService remains in beta. Capabilities in version 4.26 are only supported against ArcGIS Enterprise 11.1 and later. To access a knowledgeGraphService on ArcGIS Enterprise 11.0 and earlier, use version 4.25.

In 4.26/Enterprise 11.1, the data model and service definition of knowledge graph services were updated. With the exception of GraphSearchStreaming.globalIdsFilter, this change will not break client-side code written using the methods for knowledgeGraphService. The table below lists the knowledge graph properties that have been removed at this release:

PropertyAlternate Option
KnowledgeGraph.dataModelfetchKnowledgeGraph() returns the data model
RelationshipType.destinationEntityTypes and RelationshipType.originEntityTypesRelationshipType.endpoints
RelationshipType.strictOrigin and RelationshipType.strictDestinationnone


The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
esri/views/layers/support/FeatureEffectUse esri/layers/support/FeatureEffect instead4.22
esri/views/layers/support/FeatureFilterUse esri/layers/support/FeatureFilter instead4.22
BasemapToggle.toggle and BasemapToggleViewModel.toggle eventsWatch the activeBasemap property instead4.22
CSVLayerView.effectUse CSVLayerView.featureEffect instead4.22
FeatureLayerView.effectUse FeatureLayerView.featureEffect instead4.22
GeoJSONLayerView.effectUse GeoJSONLayerView.featureEffect instead4.22
OGCFeatureLayerView.effectUse OGCFeatureLayerView.featureEffect instead4.22
PrintViewModel.scaleEnabledUse TemplateOptions.scaleEnabled or PrintTemplate.scalePreserved instead4.22
SearchViewModel.defaultSymbolUse SearchViewModel.defaultSymbols instead4.22
StreamLayerView.effectUse StreamLayerView.featureEffect instead4.22
WFSLayerView.effectUse WFSLayerView.featureEffect instead4.22


  • Tasks have been deprecated since 4.20. They were removed at 4.24. The replacements are the classes and modules in the esri/rest folder. This will make it easier to incorporate your code into a more modular app design, and also reduce unnecessary dependencies (you only import what you want). The new rest modules are functions, which do not require constructors, so you can use their methods immediately. See the full list of removed task modules in the Complete list of removed tasks dropdown below.
  • The UI location of default widgets in a MapView or SceneView no longer changes if the app is right-to-left.
  • The API now uses WebGL2 by default, and it will fallback to WebGL1 depending on the browser. Custom WebGL layers using WebGL1-only extensions will need to be updated to detect which context is present and use the correct extension/native WebGL2 feature.
  • The properties date and displayUTCOffset have been removed from the VirtualLighting since this lighting type does not depend on the date and time. But this means that the property does not always have a date or displayUTCOffset property. For some applications that assume that this property always exists this can be a breaking change.
  • MapView.hitTest and SceneView.hitTest hit test results now return an array of GraphicHit, MediaHit, and RouteHit results. The existing apps that use the hitTest() method should be updated to check for the result type.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
FieldConfig.editorTypeSet the editor type via TextAreaInput or TextBoxInput classes set within the field element of a FeatureForm's template.4.16
widget.renderableAll properties are automatically tracked now and don't need to be decorated with this decorator.4.19

The following tasks have been deprecated for at least 3 releases and have now been removed from the API:

Task removedAlternate optionVersion deprecated
esri/portal/Portal/createClosestFacilityTaskUse closestFacility with helperServices4.21
esri/portal/Portal/createGeometryServiceUse geometryService with helperServices4.21
esri/portal/Portal/createPrintTaskUse print with helperServices4.21
esri/portal/Portal/createRouteTaskUse route with helperServices4.21
esri/portal/Portal/createServiceAreaTaskUse serviceArea with helperServices4.21
esri/tasks/supportImageIdentifyResult ImageIdentifyResult4.20


The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated


  • Removed the public .tsx Widget view source code files for all out-of-the-box widgets. This change does not affect the ability to build custom widgets, extend the ViewModel or customize widget CSS.
  • Attachment elements within popups no longer display list as the default displayType. Instead of list, it defaults to auto.
  • Originally released as beta in 4.20, the analysis layers, DirectLineMeasurementLayer and AreaMeasurementLayer, have been removed in favor of an upcoming implementation.
  • Removed justify as a possible value for TextSymbol.horizontalAlignment.
  • The basemap parameter in all smartMapping methods within the esri/smartMapping/renderers folder was deprecated at version 4.13 and is now replaced by the view parameter.
  • Updated the CoordinateConversion widget by removing the Geometry Service for cases when the coordinateFormatter didn't load due to using an outdated browser. The requestDelay property was removed from the CoordinateConversion widget and CoordinateConversionViewModel.
  • Updated the request flow of workers so that an after interceptor receives the expected data type. CSVLayer will now receive the expected data types json or text. This means after interceptors that were expecting array-buffers for client-side layers such as GeoJSONLayer and CSVLayer will now receive the expected data types json or text.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
decorators.declared()declared is no longer needed to extend Accessor anymore. See Implementing Accessor for updated information.4.16
FieldConfig.editorTypeTextAreaInput or TextBoxInput4.16
params.colorOptions.theme in univariateColorSize.createContinuousRenderer()params.theme4.18
params.colorOptions.legendOptions in univariateColorSize.createContinuousRenderer()params.legendOptions4.18
params.sizeOptions.legendOptions in univariateColorSize.createContinuousRenderer()params.legendOptions4.18
projection.isSupportedprojection.isSupported is no longer needed since support for IE11 was removed at version
widget.@renderableNo alternative is required.4.19


  • Field configurations can no longer be set on the FeatureForm. Instead, configure the fields via the FieldElement or GroupElement. Set these elements on either the form or feature layer's formTemplate.
  • ShadowAccumulation widget has been renamed to ShadowCast widget.
  • ShadowAccumulationViewModel has been renamed to ShadowCastViewModel.
  • The FeatureForm widget has changed the way it handles a a value’s input. Prior to version 4.21, field values were processed and applied using onBlur. Moving forward, this has been updated to use onInput with values getting validated as a user types. Date values will only be applied onInput if the value is valid. It will subsequently be committed or discarded onBlur based on the final value.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
FeatureForm.description and FeatureFormViewModel.descriptionFormTemplate.description set either on the FeatureForm or FeatureLayer formTemplate4.18
FeatureForm.fieldConfig and FeatureFormViewModel.fieldConfigFieldElement/GroupElement set in the FormTemplate.elements4.16
FeatureForm.title and FeatureFormViewModel.titleFormTemplate.title set either on the FeatureForm or FeatureLayer formTemplate4.18


The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated


  • The IdentityManager's setRedirectionHandler method and useSignInPage property were removed at 4.19. This was a result of Enterprise Portal apps no longer making use of this functionality beginning with the upcoming Enterprise 10.9.1 release.
  • The InputField and FieldElement hint property has been updated to display a temporary placeholder for text and number inputs for both TextAreaInput and TextBoxInput. Prior to this, whatever was set in the FieldElement's hint would display as a tooltip while hovering over the input field.
  • In order to disable any default actions in a Popup, it is now necessary to set includeDefaultActions to false. Prior to version 4.19, this was not necessary. All that was needed to remove a default action, e.g. the "Zoom to" button, was to directly set the popup's actions. This would disable the "Zoom to" button from displaying.
  • FieldElement input types of Input and TextInput have been removed in favor of exposing only their subclass types. These subclass types include TextAreaInput, TextBoxInput, and DateTimePickerInput. In addition to the latter three types, some additional new input types were also included at 4.19. These include BarcodeScannerInput, RadioButtonsInput, and ComboBoxInput. No properties or functionality was removed with Input and TextInput. These two classes' properties are now accessible directly from their subclasses.
  • esri/layers/support/AttachmentInfo has been moved to esri/rest/query/support/AttachmentInfo. While the older class will still work with JavaScript, you will need to update the reference to the new class location to get the correct typings with TypeScript.
  • The @renderable decorator has been deprecated and removed in the esri widgets helper class. Nothing else is required by the developer as widgets should still work as expected.
  • If extending a class that implements Accessor, it is no longer necessary to use dependsOn with the @property decorator when defining an Accessor property.
  • The Custom Recenter widget sample has been removed from the SDK samples. For more information visit the Custom UI basics guide page.
  • Removed the requestOptions property from the following tasks (requestOptions is still available as an optional method parameter): ClosestFacilityTask, FindTask, GeometryService, IdentifyTask, ImageIdentifyTask, ImageServiceIdentifyTask, PrintTask, RouteTask, ServiceAreaTask.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated


  • No support for IE11/Edge Legacy. Support for Internet Explorer 11 and Edge Legacy was deprecated at version 4.16, and ends at version 4.18. See our updated System Requirements page and the Why is Esri ending support for Internet Explorer 11? blog to learn more.
  • The default format for the takeScreenshot() method on MapView and SceneView has changed to png instead of jpg.
  • The mediaType property was removed from OGCFeatureLayer. All requests for metadata and data content will be made with the "f=json" url parameter.
  • FeatureForm.getValues() will now always return an Object with updated attributes. Prior to this, it would return null if there was no feature provided.
  • FeatureForm.getValues() will return undefined if there is no existing attribute on the edit feature. This is meant to distinguish from valid null values.
  • The FeatureTable widget no longer uses the layer's maxRecordCount to determine pagination size. It automatically defaults to 50 records unless the layer contains less than this. If so, it will take this count and set the pagination to it.
  • Updated the callback for intl.onLocalChange() to return a LocaleChangeCallback instead of a Function.
  • The default mode for the defaultCreateOptions on the Sketch widget has changed to click instead of hybrid.
  • The RouteParameters.barriers property has been removed. It was deprecated as of version 4.11. Use pointBarriers, polygonBarriers, and/or polylineBarriers instead.


  • For better memory management, view.destroy() now destroys all attached resources, including the map. To prevent the map from being destroyed, you can unset the map before calling destroy().
Use dark colors for code blocksCopy
// destroy the view and all attached resources

// unset map from the view so that it is not destroyed
// then destroy the view and all attached resources
const map =; = null;
  • The ActionButton and ActionToggle classes now correctly implement their types as either button or toggle. Prior to this, it was set as string.
  • The goToMedia() method in the Feature widget and its corresponding viewModel has been renamed to setActiveMedia.
  • The tables property for WebMap now takes a collection of Layers instead of an array of Objects.
  • The TimeSlider.loop property now has a default value of false instead of true.
  • Service metadata for all layers and tables are now collectively fetched from FeatureServer/layers/REST endpoint as opposed to each layer fetching its metadata from its dedicated endpoint, e.g. (FeatureServer/<layerID>).
  • StreamLayer.maximumTrackPoints was deprecated at version 4.15 and is now removed. Use StreamLayer.purgeOptions.maxObservations instead.
  • Using applyEdits to add geometries with z-values to a FeatureLayer with hasZ: false no longer silently drops the z-value and now throws an error.
  • Performance improvements were made to Popups. Prior to this release, it was possible to access the popup feature's geometry without having to specify outFields on the FeatureLayer or the PopupTemplate. It was always recommended to set this, but was never required. Going forward, if needing access to the underlying feature's geometry, this property must be set. This also holds true if working with WebMaps containing popups. If a popup does not have a referenced Arcade expression that works with geometry, it is now required to access either the WebMap's layer or its PopupTemplate and set the outFields.


  • Removed Dojo promises. Native Promises have been activated by default. The has flag "esri-native-promise" is no longer supported.
  • Removed use of Dojo’s declare module. This means that apps with classes that leverage the API class framework and multiple inheritance will stop working. The recommended approach is to use mixins with Accessor.
  • The TileImageryLayer is removed and replaced by the ImageryTileLayer.
  • The TimeExtent's intersection method now returns an instance of TimeExtent with undefined values for start and end properties if the two time extents do not intersect.
  • The suspended property of the View is now set to false when the view container's css style visibility is set to hidden (visibility:hidden). The view is hidden but it renders and updates data now.
  • CIMSymbol's data property now only supports CIMSymbolReference JSON. The CIMSymbol JSON should be applied at



  • When the propagation of an event is stopped on the View, then the propagation of any derived events are stopped. For example, when stopPropagation() is called on an immediate-click event, click and double-click events are no longer emitted. When stopPropagation() is called on an pointer-up event, immediate-click, click and double-click are no longer emitted. This makes implementing event handlers easier, since applications usually want to handle only one of those event types at a time.
  • FeatureLayerView.queryFeatures and GeoJSONLayerView.queryFeatures results will no longer include z-values in 2D MapView even if the query.returnZ is set to true.
  • The Sketch has a new property called creationMode with a default value of continuous. This allows you to continuously create graphics with same geometry types by default. This is different from the widget's default behavior in previous releases, where you could create a single graphic at a time.
  • To select or unselect multiple vertices during a graphic update operation using the Sketch widget, we now use Shift + Left-click combination instead of Ctrl + Left-click on vertices.
  • 2D measurement widgets changed the base class from esri-area-measurement-3d to esri-area-measurement-2d and from esri-direct-line-measurement-3d to esri-distance-measurement-2d.
  • Removed the getImageUrl() method from MapImageLayer. This method was deprecated since version 4.11. We recommend extending BaseDynamicLayer instead.
  • Removed the value-change and values-change events from Slider and HistogramRangeSlider. These events were deprecated since version 4.13. We recommend watching the values property or using the other widget events instead.
  • Removed Hindi (hi) as a supported locale.
  • Classes related to ArcGIS Workflow Manager have been removed. They were marked as deprecated starting with version 4.13.
  • The HTML sanitizer was added to all widgets to sanitize and escape strings according to the ArcGIS Online supported HTML specification. This can cause HTML set in PopupTemplate.content or in other widgets to be removed.




  • The behavior of FeatureLayer.outFields has changed. It is no longer computed to include fields required for layer labeling, rendering, editing and elevation info. It now returns null unless it is explicitly set.
    • In general, you no longer need to specify the outFields. The API automatically determines which fields to fetch. However, if you are using the fields in custom functionality, you might still need to explicitly add those using the outFields property.
    • To find out which fields are available client-side, use the new availableFields property. It contains a list of attribute fields fetched for each feature including fields required for layer labeling, rendering, elevation info, and any additional fields defined with the FeatureLayer.outFields property. The availableFields is populated when the layer view is finished updating.
  • Query.units property's default value is now null instead of meters.
  • Sublayer.createFeatureLayer() now returns a promise resolving to a FeatureLayer, as opposed to a FeatureLayer.
  • Autocasting is no longer supported for Mesh geometry.
  • Change to how texture transparency is interpreted in esri/geometry/support/MeshMaterial. Before, values below 0.1 would be interpreted as fully transparent (i.e. masking), now this threshold was moved to 0.5. If the old behavior is desired, the threshold can now be explicitly changed using the alphaCutoff property.
  • Moved the select method out of FeatureTemplates and into the FeatureTemplatesViewModel.
  • Removed contentEnabled property on both the Feature widget and the FeatureViewModel.
  • Removed esri/geometry/ScreenPoint class.
  • Removed Legend support from MapNotesLayer.
  • Removed token property from all layer classes. The recommended approach to pass a token on a layer is to use IdentityManager.registerToken() or to use esriConfig.request.interceptors.
  • Removed the view property from Feature widget and FeatureViewModel.
  • The MapImageLayer.getImageUrl() method now returns null.
  • Renamed definitionExpression property of AttachmentQuery class to where.
  • Renamed definitionExpression property of RelationshipQuery class to where.
  • Renamed to TemplateItemGroup.label.
  • Renamed FeatureLayerSearchSource class to LayerSearchSource.
  • As part of adding 3D drawing support, the 2D draw classes have moved:
  • Several popup related classes have been moved, renamed or removed:
    • Removed Chart class from esri/support/ContentElement/Media/Chart.
    • Removed Media class from esri/support/ContentElement/Media/Media.
    • ExpressionInfo class moved from esri/support/ExpressionInfo to esri/popup/ExpressionInfo.
    • FieldInfo class moved from esri/support/FieldInfo to esri/popup/FieldInfo.
    • LayerOptions class moved from esri/support/LayerOptions to esri/popup/LayerOptions.
    • RelatedRecordsInfo class moved from esri/support/RelatedRecordsInfo to esri/popup/RelatedRecordsInfo.
    • Renamed ContentElement class from esri/support/ContentElement to content and moved to esri/popup/content.
    • Renamed ContentElement class from esri/support/ContentElement/ContentElement to Content and moved to esri/popup/content/Content.
    • Renamed Attachments class from esri/support/ContentElement/Attachments to AttachmentsContent and moved to esri/popup/content/AttachmentsContent.
    • Renamed Fields class from esri/support/ContentElement/FieldsContent to FieldsContent and moved to esri/popup/content/FieldsContent.
    • Renamed Text class from esri/support/ContentElement/Text to TextContent and moved to esri/popup/content/TextContent.
    • Renamed Media class from esri/support/ContentElement/Media to MediaContent and moved to esri/popup/content/MediaContent.
    • Renamed BarChart class from esri/support/ContentElement/Media/BarChart to BarChartMediaInfo and moved to esri/popup/content/BarChartMediaInfo.
    • Renamed FieldsOrder class from esri/support/RelatedRecordsInfo/FieldOrder to RelatedRecordsInfoFieldOrder and moved to esri/popup/support/RelatedRecordsInfoFieldOrder.
    • Renamed Format class from esri/support/FieldInfo/Format to FieldInfoFormat and moved to esri/popup/support/FieldInfoFormat.
    • Renamed Series class from esri/support/ContentElement/Media/Chart/Series to ChartMediaInfoValueSeries and moved to esri/popup/content/support/ChartMediaInfoValueSeries.
    • Renamed Value class from esri/support/ContentElement/Media/Chart/Value to ChartMediaInfoValue and moved to esri/popup/content/support/ChartMediaInfoValue.
    • Renamed ColumnChart class from esri/support/ContentElement/Media/ColumnChart to ColumnChartMediaInfo and moved to esri/popup/content/ColumnChartMediaInfo.
    • Renamed LineChart class from esri/support/ContentElement/Media/LineChart to LineChartMediaInfo and moved to esri/popup/content/LineChartMediaInfo.
    • Renamed PieChart class from esri/support/ContentElement/Media/PieChart to PieChartMediaInfo and moved to esri/popup/content/PieChartMediaInfo.
    • Renamed Image class from esri/support/ContentElement/Media/Image to ImageMediaInfo and moved to esri/popup/content/ImageMediaInfo.
    • Renamed Value class from esri/support/ContentElement/Media/Image/Value to ImageMediaInfoValue and moved to esri/popup/content/support/ImageMediaInfoValue.
  • A graphic can only be in one GraphicsLayer at a time. When adding a graphic to a graphics layer, and if it is already in another graphics layer, the graphic is moved to the destination graphics layer.
  • The developer and user experiences for 2D highlights have been improved in three ways:
    • soft, anti-aliased edges
    • decreased default opacity that is now consistent with the default settings used in 3D
    • modified coverage algorithm that now highlights the transparent portions of lines and polygons



  • Bookmark class moved from esri/widgets/Bookmarks/Bookmark to esri/webmap/Bookmark.
  • FeatureLayer.queryFeatureAttachments() method is removed. Use FeatureLayer.queryAttachments instead.
  • Functions can no longer be used in renderers and visual variables in place of fields. Use the valueExpression property instead.
  • Removed esriConfig's request properties: corsDetection, corsDetectionTimeout, corsEnabledServers, forceProxy, and useCors properties.
  • Removed the allowImageDataAccess requestOption property from the esriRequest method. Also removed it as a property from MapImageLayer, BingMapsLayer, and OpenStreetMap options. The API automatically allows this without having to explicitly set it.
  • Removed the isMaxInclusive property from ClassBreaksRenderer.
  • Removed the popupOpenOnSelect property from Search widget and SearchViewModel.
  • Set the new trustedServers property available in esriConfig's request property if needing to include credentials such as cookies and authorization headers in cross origin requests. Prior to version 4.9, this would be handled by setting corsEnabledServers withCredentials property to true.
  • CSS style, esri-widget__header, was renamed to .esri-widget__heading. For additional information on working with this style, see the Styling guide topic.
  • SceneView.goTo() method now queries the target location for elevation if the target doesn't have a z-value. This means that the promise will not resolve immediately anymore, even if the animate option is set to false.






  • As of version 4.4, the response for the locator.locationToAddress() method returns a proper AddressCandidate. This bug fix affects two of five AddressCandidate properties: address and attributes. Note that there are no changes to the other AddressCandidate properties: extent, location and score.
    • Prior to 4.4, locationToAddress() incorrectly returned an object that always had an empty attributes property, and the address string was an object. As of 4.4, the address property is a string, and the attributes property will be populated.
    • Specifying an exact field, e.g. CountryCode, should now be written as attributes.CountryCode. (Prior to this version, it was written as address.CountryCode.)
    • The popup sample using reverse geocoding has been updated to reflect this change.
  • Esri icon font styles and codes have been updated, resulting in some codes being changed or used for new icon fonts.
  • ViewAnimation.stop() now rejects the ViewAnimation promise.
  • 3D Symbol layer types changed name style and now use kebab-casing to be consistent with the rest of the API.
  • The orientation of 3D WebStyleSymbols was updated. Now the forward-facing side of the symbol points in the direction of the y-axis (North). Setting a heading of 0 on a ObjectSymbol3DLayer will make the symbol point North and setting it to 180 will make the symbol point South. In comparison to the old styles, Signs and signals and Street scene changed orientation by 180 degrees and Transportation changed by 90 degrees.
  • As of version 4.x, the recommended approach to pass a token on a layer is to use IdentityManager.registerToken(). Prior to this in 3.x, it was possible to pass a token to a layer either via 1) the layer's token property, or 2) appending it to the end of the layer URL.
  • The Search widget's sources property has a new filter option which replaces the now deprecated searchQueryParams, suggestQueryParams, and searchExtent property.
  • If developing custom widgets, configuration settings should be updated to reflect "jsxFactory": "tsx", instead of "reactNamespace": "jsxFactory",. This is discussed in the TypeScript setup guide topic.
  • For the light values passed into external renderers, the balance between ambient and diffuse lighting has changed. This may result in a slightly different appearance for objects rendered with external renderers. The new light values represent colors/intensities in linear color space, and are optimized for gamma-corrected rendering with a gamma value of 2.1.
  • At 4.4, the event will close the popup if the clicked location doesn't intersect a feature with a popup template. You may want to disable this default behavior if opening the popup with custom content or keep it open when the view is clicked. To do so, you must call stopPropagation() on the click event object.



  • The following VectorTileLayer properties are removed: ACCESS_TOKEN
  • To increase security, browsers are starting to block Geolocation API on insecure pages, meaning that the Locate button will not work from non-secure web pages (i.e., hosted on http). Google Chrome first implemented this in version 50(April 2016) and Apple in Safari 10 (September 2016). Mozilla/Firefox is planning to do the same. At version 4.0 and 3.17 the JSAPI no longer displayed the Locate Button for non-secure web apps in the Chrome browser. As of version 4.2 and 3.19, the JSAPI no longer displays the Locate Button for non-secure web apps in any web browser. Note that localhost is considered "potentially secure" and can be used for easy testing.



This was the first official release of the 4x API. Since the prior 4x releases were in beta, they will not be considered here.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.