Get started with React and ArcGIS Maps SDK for JavaScript

For React applications, use the @arcgis/map-components npm package. The package provides industry-standard web components built on top of @arcgis/core, reducing boilerplate while keeping the underlying API fully accessible.

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 package along with its dependencies:

1
2

    npm install @arcgis/map-components

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
13
14
@import 'https://js.arcgis.com/4.32/@arcgis/core/assets/esri/themes/dark/main.css';
@import url("https://js.arcgis.com/calcite-components/3.0.3/calcite.css");
@import url("https://js.arcgis.com/map-components/4.32/arcgis-map-components.css");

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

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

Add a map

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

import "@arcgis/map-components/dist/components/arcgis-map";

const root = createRoot(document.getElementById("root") as HTMLElement);
root.render(
  <StrictMode>
    <arcgis-map
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
    >
    </arcgis-map>
  </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(
  <StrictMode>
    <arcgis-map
      itemId="d5dda743788a4b0688fe48f43ae7beb9"
      onarcgisViewReadyChange={(event: CustomEvent) => {
        console.log("MapView ready", event);
      }}
    >
        <arcgis-zoom position="top-left"></arcgis-zoom>
    </arcgis-map>
  </StrictMode>
);

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

1
2
import "@arcgis/map-components/dist/components/arcgis-map";
import "@arcgis/map-components/dist/components/arcgis-zoom";

See the tutorial for step-by-step instructions.

Bonus: TypeScript

Without typings for components in a project that uses TSX, you may encounter errors like Property 'arcgis-map' does not exist on type 'JSX.IntrinsicElements'. Assuming your project already has TypeScript configured, add the following to your vite.env.d.ts file to include component typings:

1
/// <reference types="@arcgis/map-components/types/react" />

This ensures that you will have increased type safety on components for event listeners, props, and more, making development faster and reducing the likelihood of errors.

Download project

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

• Map components sample
• @arcgis/core sample

If you are looking to explore React 18, check out the @arcgis/map-components-react package. You can download the React 18 sample project from:

• React 18 sample