All widgets are deprecated in ArcGIS Maps SDK for JavaScript 5.0 — your move to map components

Version 5.0 of the ArcGIS Maps SDK for JavaScript shipped in February 2026, and it carries one line in the release notes that changes how every new map app should be built: all widgets are now deprecated, and map components are the recommended path forward. If your app still constructs a Legend, Search, or Editor the 4.x way, it still runs today — but it is now on a clock.

This is not a same-day fire drill like a key revocation. Nothing breaks the morning after you upgrade. What it is, instead, is a clear deadline you can plan around — and a genuinely better way to build that is worth adopting on its own merits. Here is exactly what Esri changed at 5.0, what keeps working, what stops, and the migration path we use on our own portfolio.

What actually changed at 5.0

The 5.0 release notes call out three structural changes up top. They’re related, and together they signal that the SDK’s center of gravity has moved to web components:

• All widgets are deprecated. Components — the custom HTML elements in the @arcgis/map-components package — are now the recommended way to add UI to a map or scene.
• The SDK moved to semantic versioning. That’s why the jump went 4.34 → 5.0 rather than 4.35: a breaking-change boundary now gets a major version, which is exactly how you should read the widget deprecation.
• A single, module-based CDN entry point. One script tag now loads the core API, the map components, and Calcite together, replacing the three separate tags you used before.

There’s a lot of genuinely new capability in the same release — true-curve drawing and snapping in the Editor, a GaussianSplatLayer for photorealistic 3D, light-emitting symbols, and an AI components (beta) package for building agentic mapping apps. All of that ships as components, not widgets, which is the clearest tell of where the road goes.

“Deprecated” is not “broken”

It’s worth being precise, because deprecation language tends to cause either panic or apathy, and both are wrong here. Straight from the release notes: “Existing widget-based applications will continue to work as expected. Deprecation does not mean immediate removal.” Concretely:

So the failure mode isn’t a crash — it’s stagnation, then eventual removal. The longer a codebase sits on widgets, the more new functionality it can’t reach, and the larger the eventual jump to 6.0 becomes. Treat 5.0 as the moment to stop writing new widget code, then migrate the old code on a schedule.

The one change everyone hits first: the CDN tag

If you load the SDK from the CDN, this is the change you’ll make on day one. 5.0 collapses the old multi-script setup into a single module-based entry that pulls in the core API, map components, and Calcite at once:

<!-- 5.0: one module-based entry — core + map components + Calcite -->
<script type="module" src="https://js.arcgis.com/5.0/"></script>

That replaces the three tags you would have written prior to 5.0:

<!-- Prior to 5.0: Calcite + core + map components, loaded separately -->
<script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
<script src="https://js.arcgis.com/4.34/"></script>
<script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>

Two details from the release notes worth pinning down. The type="module" attribute is now required — the SDK is module-based. And if you genuinely want only the core API with no components, that’s still available at https://js.arcgis.com/5.0/core.js. For reproducible builds, 5.0 also publishes patch-pinned CDN URLs in MAJOR.MINOR.PATCH form (for example https://js.arcgis.com/5.0.0/); the MAJOR.MINOR form is an alias to the latest patch, convenient but capable of shifting under you.

The mental model: widgets are imperative, components are declarative

A 4.x widget was a JavaScript object you constructed and then pushed onto the view’s UI. A 5.0 component is a custom HTML element you place inside <arcgis-map> (or <arcgis-scene>). Same legend, two paradigms:

// 4.x widget pattern — imperative, JavaScript-only
import Legend from "@arcgis/core/widgets/Legend.js";
const legend = new Legend({ view });
view.ui.add(legend, "bottom-left");

<!-- 5.0 component pattern — declarative HTML, slotted into the map -->
<arcgis-map item-id="…your-webmap-id…">
  <arcgis-legend slot="bottom-left"></arcgis-legend>
</arcgis-map>

Note the placement change embedded there: the old position field on components was removed at 5.0 (it had been deprecated since 4.34) in favor of the standard slot attribute. Components also use a consistent lowercase, kebab-case naming convention (arcgis-feature-table, not FeatureTable), so they read like any other web component to your framework.

Migrate in five deliberate steps

1. Upgrade to 5.0 and swap to the single CDN tag (or bump @arcgis/core and @arcgis/map-components together). Confirm the app still runs on your existing widget code — it should.
2. Inventory every widget your app constructs. Anything imported from @arcgis/core/widgets/ is in scope.
3. Replace widgets with their components one surface at a time, starting with the simple chrome (Legend, Search, Home, Zoom, Basemap Gallery). Use slot for placement, and consult the migrating-to-components guide for the per-widget mapping.
4. If you write TypeScript, drop the __esri global namespace — it’s deprecated now and removed at 6.0 — in favor of direct ESM type imports. Esri ships an @arcgis/codemod package that rewrites this for you automatically.
5. Verify each migrated surface against the updated reference docs, paying special attention to components whose APIs changed (Elevation Profile, Shadow Cast) and to any legacy components you’re relying on.

Here’s the TypeScript change from step 4, since it bites quietly — the old namespace compiles until it doesn’t:

// __esri global namespace — deprecated, removed at 6.0
import type FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

let layer: FeatureLayer;        // do this
let legacy: __esri.FeatureLayer; // not this

Why this is an upgrade, not just a chore

It would be easy to read “all widgets deprecated” as pure migration tax. It isn’t. The component model is where every new capability now lands, and 5.0 makes that concrete: the AI components (beta) package introduces an arcgis-assistant chat element — with navigation, data-exploration, and help agents — for natural-language interaction with a web map. New components like Utility Network Trace Analysis, Volume Measurement (beta), and Snapping Controls arrived as components only. Declarative elements also slot more cleanly into React, Vue, and Angular than imperatively-constructed widgets ever did, which matters a great deal if, like us, you build branded React apps on top of the SDK.

The practical takeaway: every new map UI you build from today should be a component. Migrate the existing widget surfaces on a calm schedule across the next year, and you’ll reach 6.0 already on the supported path instead of scrambling when removals land.

References

• Release notes for 5.0 — ArcGIS Maps SDK for JavaScript (widget deprecation, removal in 6.0/Q1 2027, semantic versioning, CDN entry point)
• Migrating to components — ArcGIS Maps SDK for JavaScript (per-widget mapping and patterns)
• Esri’s move to web components: the transition plan
• Components overview — ArcGIS Maps SDK for JavaScript
• Building your UI: slots and component placement
• @arcgis/codemod — automated refactor for __esri types