Esri is fully committed to building standards-based web components that extend the core API of the JavaScript Maps SDK into reusable custom HTML elements, such as <arcgis-map></arcgis-map>.
This applies to both internal development of ArcGIS products, as well as the pre-built UI components that are offered as part of the JavaScript Maps SDK.
Today, the recommended approach for building web apps with the SDK is to use components.
What you need to know:
- Use components for all new development.
- Widgets are deprecated as of 5.0 and will be removed in a future release.
- For more detailed migration guidance, see Migrating to components.
Component benefits
Web components are the SDK’s recommended UI building blocks because they:
- Fit naturally into modern front-end development (HTML, CSS, and JavaScript).
- Work across frameworks (React, Angular, Vue, Svelte, etc.) and without a framework.
- Compose well with the platform: you can build layouts with standard DOM patterns instead of framework-specific wrappers.
- Align with Esri’s internal direction: components used across ArcGIS products are the same standards-based approach used in the SDK.
- Provide higher-level, ready-to-use experiences as configurable UI (for example, the Arcade Editor and Charts components).
The SDK’s collection of higher-level components will continue to grow over time.
From widgets to map components
When the SDK was first created, web component standards were still maturing, and didn’t have broad browser adoption. At the same time, we didn’t commit to a specific JS framework as the JS landscape is a constant moving target. For that reason, we developed the widget architecture and over time created more than 60 widgets for developers to use in their web apps. Now that web component standards are supported across all major browsers, we are able to evolve our technology alongside the browser (like we do for many internals of the SDK).
We have made a lot of progress with our move to components. In fact, all functionality that is available as widgets is also available as components. Initially, widgets were wrapped as web components, and over time, widgets are being reimplemented as standard web components.
In this context:
- Wrapped means the component hosts the existing widget implementation.
- Reimplemented means the component is built as a native web component (custom element) rather than relying on widget internals.
As of this release, the following map components have been reimplemented: Area Measurement 2D, Area Measurement 3D, Basemap Gallery, Basemap Toggle, Bookmarks, Building Explorer, Compass, Coordinate Conversion, Daylight, Direct Line Measurement 3D, Directional Pad, Distance Measurement 2D, Elevation Profile, Expand, Feature, Features, Floor Filter, Fullscreen, Grid Controls, Home, Legend, Line Of Sight, Locate, Navigation Toggle, Popup (beta), Print, Scale Bar, Search, Shadow Cast, Slice, Swipe, Time Zone Label, Track, Utility Network Trace Analysis, Video Player, Volume Measurement (beta), Weather, and Zoom.
While all widgets are deprecated, they will not be removed from the API until the component has been reimplemented and no longer wraps widget code.
Widget roadmap
All widgets have been deprecated at version 5.0 and will later be removed. Deprecations are signified in the release notes, API reference, and console messages. However, we are aware that while migrating to components doesn’t require an application rewrite, it does involve a reasonable amount of effort and requires planning and prioritization. Many Esri product teams are undergoing the same migration work. We are targeting the following milestone for full transition to components:
- All widgets are planned for removal from the SDK as early as Q1 2027.
View models
Along with the removal of widgets, we are putting careful thought into designing the best way to expose the view model functionality within the modernized SDK. See the blog on Evolution of view models and building custom workflows with JavaScript Maps SDK for more information, and check out the Widget view model roadmap for detailed plans for the view models going forward.
Learn more about building apps with components
There are many resources for learning how to build apps with components. For example:
- Get started guide that outlines your choices for accessing components (CDN & npm), and integration with frameworks like React and Angular.
- Component overview
- Tutorials
- Sample code that use components
- Programming patterns
- References for the core API, and the Maps SDK components.