ArcGIS Maps SDK for JavaScript web components in a custom widget | Documentation

Integrate ArcGIS Maps SDK for JavaScript web components to enhance your custom widgets with mapping capabilities.

What are ArcGIS Maps SDK for JavaScript web components?

ArcGIS Maps SDK for JavaScript web components are a collection of custom HTML elements that provide easy-to-use, framework-agnostic mapping functionality. These components allow developers to integrate ArcGIS mapping capabilities into web applications without requiring deep knowledge of the ArcGIS Maps SDK for JavaScript.

The component library includes:

arcgis-map - Display web maps
arcgis-scene - Display web scenes
arcgis-search - Add search functionality to your maps
arcgis-legend - Display map legends
arcgis-popup - Show feature information
arcgis-layer-list - Manage map layers

These components enable you to build:

Custom mapping widgets with minimal JavaScript knowledge
Interactive web applications with embedded maps
Data visualization tools with spatial context
Location-aware applications with search and geocoding capabilities

ArcGIS Experience Builder Developer Edition (DE) supports integration of ArcGIS JavaScript web components. This allows you to enhance your custom widgets with mapping functionality while maintaining the framework's capabilities.

The general steps to use map components in a custom widget are:

1. Set up your environment
Install required dependencies and configure your development environment.
2. Create custom widget
Create a custom widget in your Experience Builder project.
3. Integrate components
Import and use map components in your widget's render function.
4. Configure properties
Set component attributes and handle events for interactivity.

1. Set up your environment

You need to install ArcGIS Experience Builder Developer Edition and ensure you have the necessary development tools.

Download and install the current LTS version of Node.js.
Download and install ArcGIS Experience Builder Developer Edition.

Next, create a custom widget and set up your development environment.

Open your preferred Integrated Development Environment (IDE), such as Visual Studio Code, and navigate to the client directory in the Experience Builder project file structure.
Create a new directory for your custom widget inside the client/your-extensions/widgets directory.
Follow the directory structure outlined in Widget implementation.

3. Integrate components

Import and use the map components in your widget's render function.

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';

Alternatively, you can import the entire components package:

Use dark colors for code blocksCopy
import '@arcgis/map-components';

Add the imported components in the return statement of your widget. For example, to include a basic map component:

Use dark colors for code blocksCopy
const MyWidget = () => {
  return (
    <div>
      <arcgis-map item-id="your-webmap-item-id"></arcgis-map>
    </div>
  );
};

4. Configure properties

Set component attributes and handle events for enhanced interactivity.

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';
import { useEffect } from 'react';

const MyWidget = () => {
  useEffect(() => {
    const mapElement = document.querySelector('arcgis-map');
    if (mapElement) {
      mapElement.addEventListener('arcgisViewReadyChange', (event) => {

        const view = event.detail.view;
        // Perform actions with the view
        console.log('Map view is ready:', view);
      });
    }
  }, []);

  return (
    <div>
      <arcgis-map
        item-id="your-webmap-item-id"
        center="-118.805, 34.027"

        zoom="13"
      ></arcgis-map>
    </div>
  );
};

Code examples

These code examples show how to integrate ArcGIS Maps SDK for JavaScript web components into a custom widget for ArcGIS Experience Builder Developer Edition.

Basic map integration

One way to integrate a map component is to display a web map using its item ID:

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';

const BasicMapWidget = () => {
  return (
    <div style={{ height: '400px', width: '100%' }}>
      <arcgis-map item-id="your-webmap-item-id"></arcgis-map>
    </div>
  );
};

Map with search functionality

Add search functionality to your map widget:

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';
import '@arcgis/map-components/dist/arcgis-search.js';

const MapWithSearchWidget = () => {
  return (
    <div style={{ height: '500px', width: '100%' }}>
      <arcgis-map item-id="your-webmap-item-id">
        <arcgis-search slot="top-right"></arcgis-search>

      </arcgis-map>
    </div>
  );
};

Create a map that shows feature information:

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';
import '@arcgis/map-components/dist/arcgis-popup.js';

const InteractiveMapWidget = () => {
  return (
    <div style={{ height: '500px', width: '100%' }}>
      <arcgis-map item-id="your-webmap-item-id" popup-disabled>
        <arcgis-popup slot="popup"></arcgis-popup>
      </arcgis-map>

    </div>
  );
};

Map with legend and layer list

Add legend and layer management:

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';
import '@arcgis/map-components/dist/arcgis-legend.js';
import '@arcgis/map-components/dist/arcgis-layer-list.js';

const MapWithControlsWidget = () => {
  return (
    <div style={{ display: 'flex', height: '500px' }}>
      <div style={{ flex: '1' }}>
        <arcgis-map id="my-map" item-id="your-webmap-item-id"></arcgis-map>

      </div>
      <div style={{ width: '250px', padding: '10px' }}>
        <arcgis-legend reference-element="my-map"></arcgis-legend>
        <arcgis-layer-list reference-element="my-map"></arcgis-layer-list>

      </div>
    </div>
  );
};

Chart component integration

Add data visualization with charts components:

Use dark colors for code blocksCopy
import '@arcgis/charts-components/dist/arcgis-chart.js';
import '@arcgis/charts-components/dist/arcgis-charts-action-bar.js';


const ChartWidget = () => {
  return (
    <div style={{ height: '400px' }}>
      <arcgis-chart layer-item-id="your-feature-layer-item-id" chart-index="your-chart-index">
        <arcgis-charts-action-bar slot="action-bar"></arcgis-charts-action-bar>
      </arcgis-chart>
    </div>
  );
};

Handling map events

Handle user interactions with event handling:

Use dark colors for code blocksCopy
import '@arcgis/map-components/dist/arcgis-map.js';
import { useEffect, useState } from 'react';

const EventHandlingWidget = () => {
  const [clickedLocation, setClickedLocation] = useState(null);

  useEffect(() => {
    const mapElement = document.querySelector('arcgis-map');
    if (mapElement) {
      mapElement.addEventListener('arcgisViewReadyChange', (event) => {
        // Add click event listener
        mapElement.addEventListener('arcgisViewClick', (event) => {
          setClickedLocation({
            x: event.mapPoint.x,
            y: event.mapPoint.y,
            longitude: event.mapPoint.longitude,
            latitude: event.mapPoint.latitude
          });
        });
      });
    }
  }, []);

  return (
    <div>
      <div style={{ height: '400px', width: '100%' }}>
        <arcgis-map item-id="your-webmap-item-id"></arcgis-map>
      </div>
      {clickedLocation && (
        <div style={{ padding: '10px', backgroundColor: '#f5f5f5' }}>
          <h4>Clicked Location:</h4>
          <p>Longitude: {clickedLocation.longitude.toFixed(4)}</p>
          <p>Latitude: {clickedLocation.latitude.toFixed(4)}</p>
        </div>
      )}
    </div>
  );
};

Additional resources

For an example of integrating ArcGIS Maps SDK for JavaScript web components into a custom Experience Builder widget, go to Use Map Components sample widget in the ArcGIS Experience Builder SDK Resources repository. The sample widget provides an implementation that you can use as a starting point for your own custom widgets.

This sample widget demonstrates:

Complete widget structure with proper manifest and configuration files
Multiple component integration including maps, search, and popup components
Event handling patterns for user interactions and component lifecycle
State management using React hooks for component state
Styling and theming to match Experience Builder design patterns
Error handling and loading states for robust user experience

Tutorials

Follow instructions to build applications with ArcGIS Experience Builder.

Create a starter widget

Learn how to build the base implementation for a widget.

ArcGIS Online

Get map coordinates

Learn how to display the latitude and longitude, scale, and zoom level of the map in a custom widget..

ArcGIS Online

Add layers to a map

Learn how to add layers to a map from a custom widget.

ArcGIS Online

Get started with ArcGIS Experience Builder

Build an interactive web app about housing in America.

ArcGIS Online

Tools

Use tools to access your ArcGIS portal and create and manage content for your low-code applications.

ArcGIS Online

Create, manage, and share content and data with cloud-based GIS tools.

ArcGIS Enterprise

Create, manage, analyze, and share content and data in your portal hosted in your infrastructure.

What are ArcGIS Maps SDK for JavaScript web components?

How to use map components in a custom widget

1. Set up your environment

2. Create custom widget

3. Integrate components

4. Configure properties

1. Set up your environment

2. Create custom widget

3. Integrate components

4. Configure properties

Code examples

Basic map integration

Map with search functionality

Interactive map with popup

Map with legend and layer list

Chart component integration

Handling map events

Additional resources

Tutorials

Create a starter widget

Get map coordinates

Add layers to a map

Get started with ArcGIS Experience Builder

Tools

ArcGIS Online

ArcGIS Enterprise