If you are just getting started with the ArcGIS JavaScript API or have worked with it for a while, you may want to start integrating it into different frameworks or libraries. This guide will detail the process of getting a basic web mapping application set up in the React JavaScript library.

React is a free and open source JavaScript library designed by Meta (formerly known as Facebook) and maintained by a community of developers and companies. It allows developers to write slick client applications as a single page app (SPA). React is only used for rendering objects to the document object model (DOM) and managing the state of those objects but you can create fully fledged websites by utilising additional libraries such as React Router Dom.

In this blog post, we won’t be concerned with multiple pages and routing, instead we will focus on getting a basic web application rendered to the DOM and include a widget such as the basemap switcher.

Since writing this post, the current release ArcGIS JavaScript API is at version 4.25. To use the latest version of both the CSS and JavaScript API, simply alter all URLs from https://js.arcgis.com/4.22 to https://js.arcgis.com/4.25.

In order to follow along with this guide, you must ensure you have node.js installed and have the NPM package manager.

To save time, the create-react-app command can be run from the terminal which will give us the basic React structure to start developing our application. You can use your preferred integrated development environment (IDE) or just the default command line tool on your system.

Do this by passing in the command npx create-react-app App-Name.

In figure 1 you can see that “mapping-application” has been passed in as the argument. This argument indicates the name of the application that will be created. If you haven’t installed create-react-app, you will be prompted to install it. You can confirm this by entering “Y”.

After a few minutes, the create-react-app process will finish and you will find a new folder present in the directory you called the command from. This folder will be named the same as the argument passed in at figure 1. The folder contains all the default components used for a base react application.

Now the default react application is in place, it can be started. In the terminal change directory into the new folder that was created and run npm start. This will start the development server on your machine and will open the application in your browser. You will notice the development server is running on localhost:3000. If everything has been successful, you should see the web page displayed in figure 4.

If the browser does not automatically open, navigate to localhost:3000 manually.

The ArcGIS JavaScript API can be loaded using a few methods. You can see these detailed here. In this instance we will import the ES modules using the CDN (Content delivery network). You can however install the modules locally by running npm install @arcgis/core inside the root application folder.

Note: In order to run the build for the application, the modules must be installed locally through NPM. Building the app isn’t covered in this post.

To import the styles, open the App.css file, remove all the existing CSS and add the following:

@import "https://js.arcgis.com/4.21/@arcgis/core/assets/esri/themes/light/main.css";

Importing the classes from the JavaScript API is covered later on.

Before a map can be constructed and rendered to the browser, a new JavaScript file will be created which will store our map. In the “src” folder, create a new file called MappingApp.js. The basic layout for this will look as detailed in figure 5.

A style height has been added here to force the div to size itself to 100% of the current window. This will allow the map and map view to render correctly when we add it in. An ID has also been added to the div, this will be used later when the map view is rendered to the DOM.

The MappingApp.js file now needs importing into the App.js file so it renders to the root component of Index.js. The component path for this is Index.js > App.js > MappingApp.js.

Navigate to the App.js file and open it, import the new MappingApp.js file into it and add it to the return statement, this will render the MappingApp.js file to the DOM. Note that all of the default code that comes with create-react-app inside of App.js has been removed.

Now the mapping app file is being rendered to the DOM, a map and view can be created.

The first step is to import the required modules, as detailed previously, this example will be using the CDN rather than installing local copies of the modules.

The react hook useEffect also need importing. UseEffect allows the client to wait until the DOM is loaded before running the functional code. When a map view renders, it is mounted to a div by specifying an ID. If this code was run outside of a useEffect hook, the map view would attempt to mount to the div before it exists, which would cause an error. In this example, all the code is being executed inside of the useEffect hook.

Now the required classes have been imported, the map and map view constructors are created.

Firstly, a constant called myMap is created using the Map constructor, the “topo” basemap has been specified here however different basemaps can be set.

Next, a view variable is created using the MapView constructor, the constant myMap is specified in the map property which indicates the map that should be rendered into the view. The ID of the div is passed into the container property, this indicates where the map view should be rendered (in the DOM), in this case the document object with the ID of “MapApp”.

Finally, the centre and zoom methods have been called on the view to centre the map to the USA and set a zoom level to the full extent of the country.

The feature layer class is imported so a layer can be loaded into the map. On line 21 a new Feature Layer is constructed and bound to the layer variable. In this example the Esri sample data for the USA cities is being used. A number of different properties can be added to the layer at this point, in this case, a definition expression is applied to only show cities that have a population of 1 million or higher.

Once the layer is created, methods can be called on it, here the renderer method is called to apply a simple marker style of size 10 blue.

A popup template is added to show the city name and the population, this will by default, enable popups on the layer.

Finally, the add method is called on the myMap variable and the layer is passed in as an argument. The map should now show the layer symbolised with blue dots and popups enabled showing the custom content message.

Finally a basemap switcher widget will be added. Some widgets require minimal configuration and can be added to the map view quite easily.

The BasemapToggle class is imported and a new constructor is created and bound to a variable called basemapToggle. In the properties the view value is set to the view variable name and the nextBasemap property is set to hybrid. This will allow the user to cycle between the Topo and Hybrid basemaps.

On line 48, the widget is added to the view by calling the ui.add method and passing in the basemap toggle variable as the argument, the position of the widget is also set which dictates where it is rendered to, in this case, the top right position.

React is great versatile web library that is used by many web developers around the world. This blog post details how to get started making custom web mapping apps with React JS, this includes importing the ArcGIS Core modules, creating react component and rendering maps and widgets to the DOM.