Get started with React and ArcGIS Maps SDK for JavaScript

It is recommended to use the ArcGIS Maps SDK for JavaScript component packages in a React application. These packages such as @arcgis/map-components are built on top of @arcgis/core and the SDK uses industry standard web components to handle much of the boilerplate functionality, while ensuring the underlying API remains accessible. The benefits of the React-friendly component packages includes custom events emitted by the web components will work with React's synthetic event system, use of PascalCase instead of kebab-case elements, and in TypeScript, you will have increased type safety on components for event listeners, props, and more. In the case of @arcgis/map-components, you'd want to use @arcgis/map-components-react.

Setup

Install the @arcgis/map-components-react package:

Use dark colors for code blocksCopy
npm install @arcgis/map-components-react

Registering components

Loading all components

When using this approach to load components, you'll need to manually define the custom elements on the window and import the individual components from @arcgis/map-components-react. You can choose between ArcGIS CDN hosted assets (preferred) or local assets.

index.tsx
Use dark colors for code blocksCopy
import React from "react";
import ReactDOM from "react-dom/client";

import { ArcgisMap, ArcgisSearch, ArcgisLegend } from "@arcgis/map-components-react";

// import defineCustomElements to register custom elements with the custom elements registry
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";

defineMapElements(window, { resourcesUrl: "https://js.arcgis.com/map-components/4.30/assets" });

const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement);
root.render(
  <React.StrictMode>
    <ArcgisMap
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
      onArcgisViewReadyChange={(event: any) => {
        console.log("MapView ready", event);
      }}
    >
      <ArcgisSearch position="top-right"></ArcgisSearch>
      <ArcgisLegend position="bottom-left"></ArcgisLegend>
    </ArcgisMap>
  </React.StrictMode>
);

Individually loading components

For each component used in your application, they must be imported from the @arcgis/map-components package and the @arcgis/map-components-react package. This will automatically define the custom elements on the window. When individually loading components in the SDK, assets are loaded from the ArcGIS CDN by default. The assets include styles, images, web workers, wasm and localization files. The default asset path is "https://js.arcgis.com/map-components/4.30/assets".

index.tsx
Use dark colors for code blocksCopy
import React from "react";
import ReactDOM from "react-dom/client";

// Uncomment to work with local assets
// import { setArcgisAssetPath as setMapAssetPath} from '@arcgis/map-components/dist/components';
// setMapAssetPath(`${location.origin}${location.pathname}assets`);

import "@arcgis/map-components/dist/components/arcgis-map";
import "@arcgis/map-components/dist/components/arcgis-search";
import "@arcgis/map-components/dist/components/arcgis-legend";
import { ArcgisMap, ArcgisSearch, ArcgisLegend } from "@arcgis/map-components-react";

const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement);
root.render(
  <React.StrictMode>
    <ArcgisMap
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
      onArcgisViewReadyChange={(event: any) => {
        console.log("MapView ready", event);
      }}
    >
      <ArcgisSearch position="top-right"></ArcgisSearch>
      <ArcgisLegend position="bottom-left"></ArcgisLegend>
    </ArcgisMap>
  </React.StrictMode>
);