Using the SDK in a React app

Using the SDK with JSX in a React 19 project is similar to using it in a vanilla JavaScript and HTML project. The key differences involve JSX syntax and React programming patterns.

Before you start, make sure you are using the latest long-term support (LTS) version of node.js and npm.

Installation

To use Map components in your React project, install the @arcgis/map-components package and its dependencies:

npm install @arcgis/map-components @arcgis/core @esri/calcite-components

yarn add @arcgis/map-components @arcgis/core @esri/calcite-components

pnpm install @arcgis/map-components @arcgis/core @esri/calcite-components

Configure CSS

When using components with npm, the SDK’s component styles and Calcite styles are loaded for you. However, you still need a small amount of app CSS to make the page (and therefore the map component) fill the viewport.

Create or update index.css with the following, and make sure it’s imported in your entry file (see the index.jsx example in the next section).

html,
body {
  height: 100%;
  margin: 0;
}

Create your React component

In your entry file (for example index.jsx), import the SDK components you want to use. This registers them with the browser’s CustomElementRegistry.

When working in a framework like React, it’s generally recommended to use the SDK’s component events rather than direct method calls for better integration with the component lifecycle.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";

// Import components
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

// Import a core API module
import Graphic from "@arcgis/core/Graphic.js";

function App() {
  const handleViewReady = (event) => {
    const viewElement = event.target;

    // ...

    // Create a graphic and add the geometry and symbol to it
    const pointGraphic = new Graphic({
      geometry: point, // A point geometry
      symbol: markerSymbol, // A symbol for drawing the point
    });

    viewElement.graphics.add(pointGraphic);
  };

  return (
    <arcgis-map
        item-id="02b37471d5d84cacbebcccd785460e94"
        onarcgisViewReadyChange={handleViewReady}
    >
      <arcgis-zoom slot="top-left" />
    </arcgis-map>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(
  <StrictMode>
    <App />
  </StrictMode>,
);

See the SDK’s React template project for a complete example that shows how to work with components, the core API, OAuth, and Calcite.

TypeScript / TSX (optional)

If you already have TypeScript set up in your React 19 project and would like to use web components with TSX, you can do so with one line of code at the top of your main .tsx file or Vite’s vite-env.d.ts file. This will provide increased type safety for event listeners, properties and more.

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