Get started with React and ArcGIS Maps SDK for JavaScript

When building React applications use the @arcgis/map-components-react npm package. The package includes industry-standard web components built on top of @arcgis/core that handle much of the boilerplate functionality, while ensuring the underlying API remains accessible.

This React-friendly component package includes custom events that 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.

For more information on working with components, assets and configuring CSS, see the Get started with npm guide topic.

Steps

Install map components

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

1
npm install @arcgis/map-components-react && @arcgis/core

Configure CSS

Configure the map component's CSS to fill the height and width of its parent element. The CSS selectors and settings may vary depending on your project's unique requirements:

1
2
3
4
5
6
7
8
9
10
11
12
@import 'https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/dark/main.css';

#root,
html,
body {
  margin: 0;
}

arcgis-map {
  display: block;
  height: 100vh;
}

Configure Calcite's asset path

In the project's main file, which can be jsx or tsx, import the module for setting the Calcite components asset path and then initialize it:

1
2
3
import { setAssetPath as setCalciteComponentsAssetPath } from '@esri/calcite-components/dist/components';

setCalciteComponentsAssetPath("https://js.arcgis.com/calcite-components/2.13.2/assets");

Add a map

In the project's main file, add the arcgis-map component, its respective imports, and assign it an optional item-id if using a WebMap from ArcGIS Online, or ArcGIS Enterprise portal. See the tutorial for step-by-step instructions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import React from "react";
import ReactDOM from "react-dom/client";

import "@arcgis/map-components/dist/components/arcgis-map";
import { ArcgisMap } from "@arcgis/map-components-react";

const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement);
root.render(
  <React.StrictMode>
    <ArcgisMap
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
    >
    </ArcgisMap>
  </React.StrictMode>
);

Add additional functionality

Once that's completed, you can:

• Set properties, e.g. the basemap, center and zoom
• Use the arcgisViewReadyChange event to watch for when the view is ready or if the view's map or scene have been replaced
• Add custom JavaScript logic using the core API.

Here is an example of adding the arcgis-zoom component to the map, and then implementing the functionality to listen for change events.

Add the arcgis-zoom component inside the arcgis-map component, and assign its position to the top-left corner of the map. Then bind arcgis-map to the arcgisViewChange event:

1
2
3
4
5
6
7
8
9
10
11
12
root.render(
  <React.StrictMode>
    <ArcgisMap
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
      onArcgisViewReadyChange={(event: CustomEvent) => {
        console.log("MapView ready", event);
      }}
    >
        <ArcgisZoom position="top-left"></ArcgisZoom>
    </ArcgisMap>
  </React.StrictMode>
);

Last, add the import for arcgis-zoom at the top of the file:

1
2
3
import "@arcgis/map-components/dist/components/arcgis-map";
import "@arcgis/map-components/dist/components/arcgis-zoom";
import { ArcgisMap, ArcgisZoom } from "@arcgis/map-components-react";

See the tutorial for step-by-step instructions.

Download project

You can download the React sample project from the jsapi-resources GitHub repository:

• Map components sample
• @arcgis/core sample