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:
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:
@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.
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
arcgis
event to watch for when the view is ready or if the view's map or scene have been replacedView Ready Change - 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 arcgis
event:
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:
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 '
.
Assuming your project already has TypeScript configured, add the following to your vite.env.d.ts
file to include component typings:
/// <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:
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: