arcgis-charts

ArcGIS Charts

Use this skill when visualizing layer data as charts (bar, line, pie, histogram, scatter, etc.) using the @arcgis/charts-components package. This is a new component package in 5.0 with no 4.x equivalent.

Import Patterns

CDN (No Build Tools)

<script src="https://js.arcgis.com/5.0/"></script>  <script type="module" src="https://js.arcgis.com/5.0/charts-components/"></script>

Direct ESM Imports (Build Tools)

import "@arcgis/charts-components/components/arcgis-chart"; import "@arcgis/charts-components/components/arcgis-charts-action-bar";

Chart Models (for programmatic configuration)

import { BarChartModel } from "@arcgis/charts-components/model"; import { PieChartModel } from "@arcgis/charts-components/model"; import { LineChartModel } from "@arcgis/charts-components/model"; import { HistogramModel } from "@arcgis/charts-components/model"; import { ScatterplotModel } from "@arcgis/charts-components/model"; import { BoxPlotModel } from "@arcgis/charts-components/model"; import { GaugeModel } from "@arcgis/charts-components/model"; import { RadarChartModel } from "@arcgis/charts-components/model"; import { HeatChartModel } from "@arcgis/charts-components/model"; import { ComboBarLineChartModel } from "@arcgis/charts-components/model";

Supported Chart Types

Chart Type Model Class Description

Bar BarChartModel

Horizontal or vertical bar charts

Line LineChartModel

Line charts with series

Pie PieChartModel

Pie and donut charts

Histogram HistogramModel

Frequency distribution histograms

Scatter ScatterplotModel

Scatter and bubble plots

Box Plot BoxPlotModel

Box and whisker plots

Gauge GaugeModel

Gauge / speedometer charts

Radar RadarChartModel

Radar / spider charts

Heat Chart HeatChartModel

Heat / matrix charts

Combo ComboBarLineChartModel

Combined bar and line charts

arcgis-chart Component

Core Properties

Property Attribute Type Default Description

model

ChartModel | WebChart

Chart configuration model (set via JS)

layer

FeatureLayerView | SupportedLayer

Data source layer (set via JS)

view

MapView | SceneView

Map/scene view reference (set via JS)

layerItemId

layer-item-id

string

Layer portal item ID (alternative to layer )

chartIndex

chart-index

number

Index of chart to render when a layer has multiple charts

actionMode

action-mode

string

Interaction mode: "zoom" , "multiSelection" , "multiSelectionWithCtrlKey" , "pan"

Display Properties

Property Attribute Type Default Description

disableInteractions

disable-interactions

boolean

false

Disable all chart interactions

enableConfiguration

enable-configuration

boolean

false

Enable built-in chart configuration UI

enableResponsiveFeatures

enable-responsive-features

boolean

Enable responsive behavior

useAnimatedCharts

use-animated-charts

boolean

Enable chart animations

hideEmptySeries

hide-empty-series

boolean

Hide series with no data

hideLicenseWatermark

hide-license-watermark

boolean

Hide license watermark

hideLoaderAnimation

hide-loader-animation

boolean

Hide loading animation

placeholder

string

Placeholder text when no data

showUIMessages

show-ui-messages

boolean

Show user-facing messages

errorPolicy

error-policy

string

"throw"

Error handling: "throw" or "ignore"

Data and Filtering Properties

Property Attribute Type Default Description

filterByExtent

filter-by-extent

boolean

Filter chart data by current map extent

filterBySelection

filter-by-selection

boolean

Filter chart data by map selection

syncSelection

sync-selection

boolean

false

Sync selection between chart and map

runtimeDataFilters

WebChartDataFilters

Runtime data filters (set via JS)

selectionData

SelectionData

Current selection data

nullAsValid

null-as-valid

boolean

false

Treat null values as valid data points

timeZone

time-zone

string

Time zone for temporal data

Formatter Callbacks

Property Type Description

dataLabelFormatter

function

Custom formatting for data labels

tooltipFormatter

function

Custom formatting for tooltips

xAxisLabelFormatter

function

Custom formatting for X-axis labels

yAxisLabelFormatter

function

Custom formatting for Y-axis labels

gaugeInnerLabelFormatter

function

Custom formatting for gauge inner labels

guideTooltipFormatter

function

Custom formatting for guide tooltips

Methods

Method Returns Description

loadModel()

Promise<void>

Load the chart model

refresh(props?)

Promise<void>

Refresh chart; optional { updateData, resetAxesBounds }

resetZoom()

Promise<void>

Reset zoom to default view

clearSelection()

Promise<void>

Clear all selections

switchSelection()

Promise<void>

Switch selection state

exportAsImage(format?)

Promise<void>

Export chart as "png" , "jpg" , or "svg"

exportAsCSV(options?)

Promise<void>

Export chart data as CSV file

errorAlert(message?)

Promise<void>

Display an error alert

notify(message?, heading?)

Promise<void>

Show a notification

componentOnReady()

Promise<this>

Resolves when the component is fully loaded

Events

Event Detail Description

arcgisSelectionChange

Fired when the chart selection changes

arcgisDataFetchComplete

WebChartDataTypes

Fired when data has been fetched

arcgisDataProcessComplete

Fired when data processing is complete

arcgisUpdateComplete

ValidationStatus

Fired when chart updates are complete

arcgisConfigChange

{ newConfig, oldConfig, functionCalled }

Fired when chart configuration changes

arcgisAxesMinMaxChange

AxesMinMaxChangePayload

Fired when axes min/max are computed

arcgisBadDataWarningRaise

DataWarningObject

Fired when a data error is detected

arcgisChartNotFoundWarning

string

Fired when a referenced chart is not found

Basic Usage

Chart from a FeatureLayer

<arcgis-map id="map" item-id="YOUR_WEBMAP_ID"> <arcgis-zoom slot="top-left"></arcgis-zoom> </arcgis-map> <div id="chart-container" style="width: 500px; height: 400px;"> <arcgis-chart id="my-chart"></arcgis-chart> </div>

await mapElement.viewOnReady(); const view = mapElement.view;

// Get the layer const layer = view.map.layers.find(l => l.title === "My Layer"); await view.whenLayerView(layer);

// Assign layer and view to chart chartElement.layer = layer; chartElement.view = view;

// Create a bar chart model const { BarChartModel } = await $arcgis.import( "@arcgis/charts-components/model" );

const model = new BarChartModel(); model.layer = layer;

chartElement.model = model; </script>

Chart with WebChart Spec (JSON Configuration)

const chartElement = document.querySelector("arcgis-chart"); chartElement.layer = layer; chartElement.view = view;

// WebChart JSON specification chartElement.model = { type: "bar", title: { visible: true, text: "Population by State" }, series: [{ type: "bar", query: { orderByFields: ["Population DESC"], groupByFieldsForStatistics: ["State"], outStatistics: [{ statisticType: "sum", onStatisticField: "Population", outStatisticFieldName: "TotalPop" }] }, x: "State", y: "TotalPop" }] };

Pie Chart

const { PieChartModel } = await $arcgis.import( "@arcgis/charts-components/model" );

const model = new PieChartModel(); model.layer = layer;

const chartElement = document.querySelector("arcgis-chart"); chartElement.layer = layer; chartElement.view = view; chartElement.model = model;

Line Chart

const { LineChartModel } = await $arcgis.import( "@arcgis/charts-components/model" );

const model = new LineChartModel(); model.layer = layer;

const chartElement = document.querySelector("arcgis-chart"); chartElement.layer = layer; chartElement.view = view; chartElement.model = model;

arcgis-charts-action-bar Component

Provides a toolbar for chart interactions (export, selection, filtering, zoom).

Setup

// Connect action bar to chart actionBar.chartElement = chart; </script>

Key Action Bar Properties

Property Attribute Type Default Description

chartElement

chart-element

ArcgisChart

Reference to the chart component

expanded

boolean

false

Whether the action bar is expanded

exportAsImageState

export-as-image-state

string

"enabled"

Image export button state

exportAsCSVState

export-as-csv-state

string

"enabled"

CSV export button state

filterByExtentState

filter-by-extent-state

string

"enabled"

Filter by extent button state

filterBySelectionState

filter-by-selection-state

string

"enabled"

Filter by selection button state

zoomState

zoom-state

string

"enabled"

Zoom button state

forceDisableActions

force-disable-actions

boolean

false

Disable all actions at once

hiddenActions

DefaultChartActions[]

Array of actions to hide

Action states can be "enabled" , "disabled" , or "hidden" .

Selection and Filtering

Sync Selection Between Chart and Map

const chart = document.querySelector("arcgis-chart"); chart.syncSelection = true; chart.layer = layer; chart.view = view;

// Listen for selection changes chart.addEventListener("arcgisSelectionChange", () => { console.log("Selection changed:", chart.selectionData); });

Filter Chart by Map Extent

const chart = document.querySelector("arcgis-chart"); chart.filterByExtent = true; chart.view = view; chart.layer = layer;

Runtime Data Filters

const chart = document.querySelector("arcgis-chart"); chart.runtimeDataFilters = { where: "Population > 100000", orderByFields: ["Population DESC"] };

Export

Export as Image

const chart = document.querySelector("arcgis-chart"); await chart.exportAsImage("png"); // "png", "jpg", or "svg"

Export as CSV

const chart = document.querySelector("arcgis-chart"); await chart.exportAsCSV();

Custom Formatters

Data Label Formatter

Tooltip Formatter

chart.tooltipFormatter = (tooltipData) => { return <b>${tooltipData.category}</b>: ${tooltipData.value.toLocaleString()}; };

Axis Label Formatter

chart.xAxisLabelFormatter = (value) => { // Truncate long labels return String(value).length > 15 ? String(value).slice(0, 12) + "..." : String(value); };

CDN Full Example

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Chart from Feature Layer</title> <script src="https://js.arcgis.com/5.0/"></script> <script type="module" src="https://js.arcgis.com/5.0/charts-components/"></script> <script type="module" src="https://js.arcgis.com/5.0/map-components/"></script> <style> html, body { height: 100%; margin: 0; display: flex; } arcgis-map { flex: 1; } #chart-panel { width: 400px; height: 100%; } </style> </head> <body> <arcgis-map id="map" item-id="YOUR_WEBMAP_ID"> <arcgis-zoom slot="top-left"></arcgis-zoom> </arcgis-map> <div id="chart-panel"> <arcgis-chart id="chart"></arcgis-chart> <arcgis-charts-action-bar id="action-bar"></arcgis-charts-action-bar> </div>

await mapElement.viewOnReady();
const view = mapElement.view;
const layer = view.map.layers.getItemAt(0);
await view.whenLayerView(layer);

const { BarChartModel } = await $arcgis.import(
  "@arcgis/charts-components/model"
);

const model = new BarChartModel();
model.layer = layer;

chartElement.layer = layer;
chartElement.view = view;
chartElement.model = model;
chartElement.syncSelection = true;

actionBar.chartElement = chartElement;

</script> </body> </html>

Common Pitfalls

Missing layer property: The chart requires a layer data source. Setting only model without layer produces an empty chart.

// Anti-pattern: model without layer chartElement.model = new BarChartModel();

// Correct: set both layer and model const model = new BarChartModel(); model.layer = layer; chartElement.layer = layer; chartElement.model = model;

Impact: The chart renders its frame and axes but shows no data.

Chart component not loaded: The charts package must be explicitly loaded via CDN or imported.

<script src="https://js.arcgis.com/5.0/"></script> <arcgis-chart></arcgis-chart>

<script src="https://js.arcgis.com/5.0/"></script> <script type="module" src="https://js.arcgis.com/5.0/charts-components/"></script> <arcgis-chart></arcgis-chart>

Impact: The arcgis-chart element is not defined and renders as an empty inline element.

Setting model as an HTML attribute: The model property accepts complex objects and must be set via JavaScript, not as an HTML attribute.

Impact: The attribute value is ignored; the chart shows no data.

Using filterByExtent without view : Extent filtering requires the view property to track the current map extent.

// Anti-pattern: filterByExtent without view chart.filterByExtent = true; chart.layer = layer;

// Correct: set view for extent filtering chart.filterByExtent = true; chart.layer = layer; chart.view = view;

Impact: The filter has no extent to reference and may throw errors or show all data.

Action bar not connected: The action bar needs a reference to the chart element.

// Anti-pattern: action bar without chart reference const actionBar = document.querySelector("arcgis-charts-action-bar"); // Missing: actionBar.chartElement = chartElement;

Impact: Action bar buttons are visible but do nothing when clicked.

Reference Samples

arcade-execute-chart
Execute Arcade expressions and build charts from results
featurereduction-cluster-popup-chart
Charts inside cluster popups
featurereduction-cluster-pie-charts
Pie chart cluster representations
visualization-pie-chart
Pie chart visualization

Related Skills

See arcgis-layers for configuring FeatureLayers that supply chart data.
See arcgis-core-maps for setting up the MapView referenced by charts.
See arcgis-arcade for Arcade expressions used with chart data computation.
See arcgis-widgets-ui for layout components to host chart panels.

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

arcgis-widgets-ui

arcgis-popup-templates

arcgis-geometry-operations

arcgis-core-maps