react-arcgis

by Esri

A few components to help you get started using the ArcGIS API for JavaScript and esri-loader with Re...

229 Stars 55 Forks Last release: 5 months ago (5.1.0) Apache License 2.0 363 Commits 3 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

react-arcgis

Version build status Test Coverage

This project provides a library with a few ready to use React components (

,
, 
, and 
) to get you started using the ArcGIS API for JavaScript in your React application. These components use esri-loader under the hood to lazy-load the ArcGIS API modules.

IMPORTANT: You do not need

react-arcgis
to use the ArcGIS API in your React application. If the above generic components do not suit your needs you can very easily create your own React components that load the ArcGIS API for JavaScript using esri-loader. Alternatively, you could get started with the components in this library and then add your own components as needed.

Installation

  1. Run
    npm i --save esri-loader @esri/react-arcgis
    in your React application

If you need to support browsers lacking a native promise implementation, you will have to add a global

Promise
constructor polyfill to your project, as react-arcgis does not include one. See the esri-loader documentation for more details.

Basic Usage

IMPORTANT: You must load ArcGIS API styles before using the components in this library. The snippets below assume you've already used one of the ways that

esri-loader
provides you with to load the ArcGIS API CSS.

Render a simple map in React:

import React from 'react';
import * as ReactDOM from 'react-dom';
import { Map } from '@esri/react-arcgis';

ReactDOM.render( , document.getElementById('container') );

map

Or, render a 3D web-scene:

import React from 'react';
import * as ReactDOM from 'react-dom';
import { Scene } from '@esri/react-arcgis';

ReactDOM.render( , document.getElementById('container') );

You can also add webmaps and webscenes from ArcGIS Online:

import React from 'react';
import * as ReactDOM from 'react-dom';
import { WebMap, WebScene } from '@esri/react-arcgis';

ReactDOM.render(

, document.getElementById('container') );

webmap

If you want to change the style of the

Map
or
Scene
, just give it a class:
import React from 'react';
import * as ReactDOM from 'react-dom';
import { Scene } from '@esri/react-arcgis';

ReactDOM.render( , document.getElementById('container') );

You can also pass properties into the

Map
,
MapView
, or
SceneView
via the viewProperties or mapProperties props:
import React from 'react';
import { Map } from '@esri/react-arcgis';

export default (props) => ( )

map-properties

These properties are passed directly to the available properties on the corresponding ArcGIS API classes:

import React from 'react';
import { Scene } from '@esri/react-arcgis';

export default (props) => ( )

scene

If you want to access the

map
and
view
instances directly after they are loaded, pass in an
onLoad
handler:
import React from 'react';
import { Map } from '@esri/react-arcgis';

export default class MakeAMap extends React.Component { constructor(props) { super(props); this.state = { map: null, view: null };

    this.handleMapLoad = this.handleMapLoad.bind(this)
}

render() {
    return <map classname="full-screen-map" onload="{this.handleMapLoad}"></map>;
}

handleMapLoad(map, view) {
    this.setState({ map, view });
}

}

Don't forget an

onFail
handler in case something goes wrong:
import React from 'react';
import { WebScene } from '@esri/react-arcgis';

export default class MakeAScene extends React.Component { constructor(props) { super(props); this.state = { status: 'loading' };

    this.handleFail = this.handleFail.bind(this);
}

render() {
    return <webscene classname="full-screen-map" id="foobar" onfail="{this.handleFail}"></webscene>;
}

handleFail(e) {
    console.error(e);
    this.setState({ status: 'failed' });
}

}

Advanced Usage

Configuring
esri-loader

By default, the components in this library will use

esri-loader
's default options, which means they will lazy-load the modules from the CDN version of the ArcGIS API for JavaScript used by the version of
esri-loader
you have installed. See the
esri-loader
configuration documentation
for information on how you can customize
esri-loader
's behavior.

Using
setDefaultOptions()

The easiest way to do this is by calling

esri-loader
's
setDefaultOptions()
once at application startup before any of the components in this library are rendered.
import React from 'react';
import * as ReactDOM from 'react-dom';
import { setDefaultOptions } from 'esri-loader';
// app contains react-arcgis components
import { App } from './components/App.js';

// configure esri-loader to lazy load the CSS // the fisrt time any react-arcgis components are rendered setDefaultOptions({ css: true });

ReactDOM.render( , document.getElementById('app') );

This requires

[email protected]^2.12.0
. If you are using an older version of esri-loader you should probably upgrade.

Using
loaderOptions

If you can't use

setDefaultOptions()
, you can use the
loaderOptions
prop provided by each of the components in this library. That will be passed as
options
to
loadModules()
. Keep in mind that if you use
loaderOptions
, you must pass the same options to all
react-arcgis
components in your application, as well as any places where your application calls
loadModules()
directly.

Creating Your Own Components

The functionality available through the ArcGIS API for JavaScript goes well beyond just rendering maps, and if your application needs to do more with the map than simply show it, you will likely need to load and use additional classes from the ArcGIS API and provide the instances of those classes with references to the maps you've created with the components in this library.

Fortunately you've already installed

esri-loader
, which allows you to load any additional ArcGIS API modules your application might need. Also,
react-arcgis
provides the children of
,
, 
, and 
 with access to their parent's 
map
and
view
instances through props.

For example, let's convert a Bermuda Triangle graphic from this example into a react component:

import { useState, useEffect } from 'react';
import { loadModules } from 'esri-loader';

const BermudaTriangle = (props) => {

const [graphic, setGraphic] = useState(null);
useEffect(() =&gt; {

    loadModules(['esri/Graphic']).then(([Graphic]) =&gt; {
        // Create a polygon geometry
        const polygon = {
            type: "polygon", // autocasts as new Polygon()
            rings: [
                [-64.78, 32.3],
                [-66.07, 18.45],
                [-80.21, 25.78],
                [-64.78, 32.3]
            ]
        };

        // Create a symbol for rendering the graphic
        const fillSymbol = {
            type: "simple-fill", // autocasts as new SimpleFillSymbol()
            color: [227, 139, 79, 0.8],
            outline: { // autocasts as new SimpleLineSymbol()
                color: [255, 255, 255],
                width: 1
            }
        };

        // Add the geometry and symbol to a new graphic
        const graphic = new Graphic({
            geometry: polygon,
            symbol: fillSymbol
        });
        setGraphic(graphic);
        props.view.graphics.add(graphic);
    }).catch((err) =&gt; console.error(err));

    return function cleanup() {
        props.view.graphics.remove(graphic);
    };
}, []);

return null;

}

export default BermudaTriangle;

Now we can use the

 component within our 
,
, 
, or 
, and the 
map
and
view
props will automatically be supplied by react-arcgis:
import * as React from 'react';
import { Scene } from '@esri/react-arcgis';
import BermudaTriangle from './BermudaTriangle'; // The Graphic component we just made

export default (props) => ( )

bermuda-triangle

Using the ArcGIS Types

See the

esri-loader
documentation on working with ArcGIS types.

Migrating

From v4 to v5

First, make sure esri-loader is installed as a dependency of your application:

npm install --save esri-loader

Then, update any

import
statements for
loadModules()
:
// Replace old `loadModules` imports...
// import { Map, loadModules } from '@esri/react-arcgis';

// With a new, separate esri-loader import: import { Map } from '@esri/react-arcgis'; import { loadModules } from 'esri-loader';

Contributions

Anyone is welcome to contribute to this package. However, we do not plan to add any more components to this library. If you have created a component that you'd like to share, we encourage you to share it via CodeSandbox or a gist. Once you've done that feel free to open an issue and we'll help spread the word.

We gladly welcome bug fixes or improvements to documentation.

Here are some commands that may be helpful for development:

  • npm test
    : Runs the unit tests
  • npm run build
    : Builds the application

To run the demo application against the code you are developing, you'll need to run these commands:

npm link
npm run build
cd demo
npm i
npm link @esri/react-arcgis
npm start

Keep in mind that the

start
script only watches for changes to code in the demo app. You'll have to re-run
npm run build
each time you make changes in to the library and want to verify them in the demo app.

License

Copyright © 2017-2019 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.