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
.
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.
Component benefits
This shift in architecture maximizes productivity of front-end web development. Custom elements provide a familiar (HTML, CSS, JS) programming experience and enable seamless integration with application frameworks. In addition, since we are encapsulating ArcGIS experiences as web components in Esri products, we are able deliver proven workflows as configurable components in the SDK (such as the already released 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. To see a list of components that have completed this transition in 4.32, see 4.32 release notes. Once we finish reimplementing components, we will add support for slots, which will enable you to integrate custom controls and functionality within the component experience.
SDK website and associated resources in transition
Many resources in the SDK are already component-based. This includes new and updated resources such as the get started guides, programming patterns, tutorials, a collection of samples, integration of the component playground and API reference, and more. However, as the SDK website includes resources that we have been working on for over 8 years, a full transition will take multiple releases. While we are in transition, you will see samples and code snippets throughout the website that are not yet reflecting the recommended coding patterns (i.e. aren’t component-based). Every release will bring notable progress.
Widget roadmap
Eventually, all widgets will be deprecated and later removed. 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 will be undergoing the same migration work. The widget roadmap factors in this required effort, as well as our component development roadmap. We are targeting the following milestones for full transition to components:
- Once a component in the @arcgis/map-components package has been updated in their implementation to no longer wrap widget code, the equivalent widget will be deprecated. Deprecations will be signified in the API reference, sample code, and in console messages.
- For 4.32, this applies to 12 map components: Basemap Gallery, Basemap Toggle, Compass, Directional Pad, Fullscreen, Home, Locate, Navigation Toggle, Scale Bar, Swipe, Track, and Zoom components.
- All widgets will be deprecated as early as Q1 2026.
- All widgets will be removed from the SDK as early as Q1 2027.
Learn more about building apps with components
There are many resources for learning how to build apps with components. For example:
- Get started resources, including guides that outline 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.