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

Use the Charts component from ArcGIS Maps SDK for JavaScript components to display data in your Experience Builder widget.

What are ArcGIS Maps SDK for JavaScript components?

ArcGIS Maps SDK for JavaScript provides a collection of web components that expose ArcGIS functionality as custom HTML elements. They are framework‑agnostic, reactive, and reduce boilerplate when embedding mapping, visualization, and analysis capabilities.

Core component categories:

Category	Components	Purpose
Map and Scene	`<arcgis-map>`, `<arcgis-scene>`	Display 2D maps and 3D scenes
Layer and Legend	`<arcgis-layer-list>`, `<arcgis-legend>`	Manage and explain layers
Search and Locate	`<arcgis-search>`, `<arcgis-locate>`	Geocoding and device location
Basemap and Navigation	`<arcgis-basemap-gallery>`, `<arcgis-home>`, `<arcgis-navigation-toggle>`	Change basemap and navigate
UX Utilities	`<arcgis-expand>`, `<arcgis-time-slider>`, `<arcgis-bookmarks>`	UI framing and temporal navigation
Editing and Drawing	`<arcgis-sketch>`	Feature sketching/edit tools
Measurement and Coordinates	`<arcgis-measurement>`, `<arcgis-coordinate-conversion>`	Distance/area and format conversion
Popup and Info	`<arcgis-popup>`	Feature info display
Charts and Analysis	`<arcgis-chart>`, `<arcgis-charts-action-bar>`	Data visualization
Attribution and Scale	`<arcgis-attribution>`, `<arcgis-scale-bar>`	Map metadata and scale

When to use components

You can use ArcGIS Maps SDK for JavaScript components in custom widgets for ArcGIS Experience Builder Developer Edition. Components simplify embedding mapping functionality with minimal code. You use these components when you need rapid assembly of mapping UI, consistent ArcGIS behavior, minimal direct SDK code, or isolated functionality inside Experience Builder custom widgets.

Here are the general steps:

1. Create your widget
Create your widget folder and files.
2. Integrate components
Import elements and render them in React.
3. Configure and handle events
Set attributes, listen for lifecycle and user events.
4. Enhance and optimize
Combine components, manage state, and optimize performance.

Set up your custom widget structure in Experience Builder Developer Edition.

Go to how to install Experience Builder developer edition to set up your development environment.
Follow getting started with widget development to create your widget folder and files.

2. Integrate components

Map components and Charts components are pre-installed in Experience Builder Developer Edition. Import the components you want to use in your widget's main TypeScript file.

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

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>
  );
};

3. Configure and handle events

Once you've added components to your widget, you can configure them by setting attributes and handle events using standard DOM event listeners.

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>
  );
};

4. Enhance and optimize

You can enhance your widget by combining multiple components, managing state with React hooks, and optimizing performance through lazy loading and conditional rendering.

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';
import { useEffect, useState } from 'react';

const EnhancedWidget = () => {
  const [mapReady, setMapReady] = useState(false);

  useEffect(() => {
    const mapElement = document.querySelector('arcgis-map');
    if (mapElement) {
      const handleViewReady = (event) => {
        setMapReady(true);
        const view = event.detail.view;
        // Additional view setup
      };

      mapElement.addEventListener('arcgisViewReadyChange', handleViewReady);

      return () => {
        mapElement.removeEventListener('arcgisViewReadyChange', handleViewReady);
      };
    }
  }, []);

  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' }}>
        {mapReady && (
          <>
            <arcgis-legend reference-element="my-map"></arcgis-legend>
            <arcgis-layer-list reference-element="my-map"></arcgis-layer-list>
          </>
        )}
      </div>
    </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 components?

When to use components

Use components in a custom widget

1. Create your widget

2. Integrate components

3. Configure and handle events

4. Enhance and optimize

1. Create your widget

2. Integrate components

3. Configure and handle events

4. Enhance and optimize

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