Skip to content
ESM
import "@arcgis/charts-components/components/arcgis-chart";
Inheritance:
ArcgisChartPublicLitElement
Since
ArcGIS Maps SDK for JavaScript 4.32

The Chart component renders a chart based on the provided model. Get started by reading the introduction to charts page.

Supported chart types include bar charts, box plots, line charts, combo bar-line charts, gauges, heat charts, histograms, pie charts, scatterplots, and radar charts.

See also
  • Introduction to charts

  • Tutorial: Display a chart

    Note: When the chart is getting rendered while its container is not yet fully sized, a console error about the chart's attribute height may appear. This is a known issue and should not affect the functionality of the chart.

Demos

Properties

PropertyAttributeType
action-mode
allow-using-object-id-stat
auto-destroy-disabled
autoDisposeChart
deprecated
auto-dispose-chart
auto-inverse-data-label-text-color
chart-index
cursor-range
ChartOptions["dataLabelFormatter"] | undefined
disable-interactions
disable-toggling-legend-items
enable-configuration
enable-responsive-features
error-policy
featureIndex
deprecated
feature-index
filter-by-extent
filter-by-selection
hide-empty-series
hide-license-watermark
hide-loader-animation
ignore-smooth-rendering-limit
ignore-view-extent
layer-fields-change-policy
layer-filter-change-policy
layer-item-id
layer-renderer-change-policy
legendPosition
deprecated
legend-position
legendVisibility
deprecated
legend-visibility
null-as-valid
placeholder
queue-chart-creation
replace-no-value-category-with-zero
return-features-extent
return-selection-indexes
return-selection-oi-ds
rotation
deprecated
rotation
set-time-binning-info-when-not-provided
show-ui-messages
sync-selection
sync-selections-between-chart-and-layer-view-policy
time-zone
MapView["timeZone"] | undefined
ChartOptions["tooltipFormatter"] | undefined
use-animated-charts
use-popup-template-fields-info
view-time-extent-change-policy

actionMode

Property
Type
ActionModes | undefined

Specifies the user action behavior for the chart.

  • monoSelection: Select a single data point or series, new selection replaces the previous one.
  • multiSelection: Select multiple data points or series, new selection adds to the previous one.
  • multiSelectionWithCtrlKey: Select multiple data points or series while holding the Ctrl key (Cmd on Mac). When the key is held, each new selection is added; otherwise, the selection is replaced.
  • none: No action is performed on user interaction.
  • zoom: Zoom into a specific area of the chart.

Note: Not applicable to gauge.

Attribute
action-mode

allowUsingObjectIdStat

Property
Type
boolean

Whether to allow the object id to be used as a statistic other than COUNT.

Attribute
allow-using-object-id-stat
Default value
false

aria

Property
Type
DOMContainerAria
Since
ArcGIS Maps SDK for JavaScript 5.0

The ARIA attributes for the chart.

autoDestroyDisabled

Property
Type
boolean

When true, the chart will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the chart to a different place on the page, or temporarily hide it.

Attribute
auto-destroy-disabled
Default value
false

autoDisposeChart

deprecated Property
Type
boolean | undefined

Auto disposes the chart when a new one is created in the same container.

Attribute
auto-dispose-chart
Default value
false

autoInverseDataLabelTextColor

Property
Type
boolean | undefined

When true, the data label text color is automatically adjusted for readability based on its background. If the label is dark and appears over a dark series area, the text color is switched to either the chart background color or white.

Attribute
auto-inverse-data-label-text-color
Default value
false

chartIndex

Property
Type
number | undefined

The index of the chart to be rendered from the layer. Must be used in conjunction with the layerItemId or layer property.

If a layer or layerItemId is set without chartIndex, the first chart in the layer will be rendered.

If the chartIndex is out of bounds, the first chart in the layer will be rendered and a warning event will be emitted.

Attribute
chart-index
Example
<arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2"></arcgis-chart>

chartLimits

Property
Type
ChartElementLimit | undefined

Used to customize the number maximum of bars allowed on the chart.

The chart's behavior once that limit is reached can be adjusted through the behaviorAfterLimit nested property, to either reject the creation or update of the chart, or render the elements up to the given limits.

Note: Not applicable to gauge.

chartWillRender

Property
Type
PreRenderCallback | undefined

Lifecycle function executed after the data has been processed and before the chart renders. Can be used to alter the config from information extracted from the data for instance.

Note: Applicable to gauge and pie chart only.

cursorRange

Property
Type
CursorRange | undefined

Sets the cursor range when actionMode is set to zoom, multiSelection or multiSelectionWithCtrlKey.

  • multi-axes: Allows to draw a free rectangle.
  • x-axis: Allows to draw a rectangle bound to the x-axis.
  • y-axis: Allows to draw a rectangle bound to the y-axis.
  • undefined: Defaults to the preset behavior according to the chart type and action mode.

Note: Not applicable to gauge.

Attribute
cursor-range

dataLabelFormatter

Property
Type
ChartOptions["dataLabelFormatter"] | undefined

A callback function used to format the data labels. If the returned string contains HTML tags they will be interpreted as such.

Note: Not applicable to gauge.

disableInteractions

autocast Property
Type
boolean

Disables all interactions on the chart.

Attribute
disable-interactions
Default value
false

disableTogglingLegendItems

Property
Type
boolean | undefined

Disables the toggling of series via the legend items.

Note: Only applicable to multi-series charts.

Attribute
disable-toggling-legend-items
Default value
false

enableConfiguration

Property
Type
boolean

Whether to use features uniquely designed for a chart currently being configured by a user via the UI.

Attribute
enable-configuration
Default value
false

enableResponsiveFeatures

Property
Type
boolean | undefined

Enables the responsive features.

Attribute
enable-responsive-features
Default value
false

errorPolicy

Property
Type
ErrorPolicy

Whether to display an error alert and hide the chart when it can't be created or updated.

Attribute
error-policy
Default value
"throw"

featureIndex

deprecated Property
Type
number | undefined

The index of the feature to render when using a feature based gauge.

Note: Only applicable to gauge.

Attribute
feature-index

filterByExtent

Property
Type
boolean | undefined

When true, all chart elements are filtered based on the view extent.

Attribute
filter-by-extent
Default value
false

filterBySelection

Property
Type
boolean | undefined

When true, all chart elements are filtered based on the selection.

Note: Not applicable to gauge.

Attribute
filter-by-selection
Default value
false

gaugeInnerLabelFormatter

Property
Type
GaugeInnerLabelFormatCallback | undefined

A callback function used to format the gauge inner label. If the returned string contains HTML tags they will be interpreted as such.

Note: Applicable to gauge only.

guideTooltipFormatter

Property
Type
GuideTooltipFormatCallback | undefined

A callback function used to format the axes guides tooltip. If the returned string contains HTML tags they will be interpreted as such.

Note: Not applicable to pie chart.

hideEmptySeries

Property
Type
boolean | undefined

When true, the empty series are completely hidden from the chart and the legend. For example, a series may become empty after applying a data filter, filter by attribute or geometry (as when using the filter by extent).

Note: Not applicable to gauge.

Attribute
hide-empty-series
Default value
false

hideLicenseWatermark

Property
Type
boolean | undefined

Hides the license watermark.

Attribute
hide-license-watermark
Default value
false

hideLoaderAnimation

Property
Type
boolean | undefined

Hides the loader animation (curtain and spinner), showed by default at every update.

Attribute
hide-loader-animation
Default value
false

ignoreSmoothRenderingLimit

Property
Type
boolean | undefined

When true, disables the default setting that uses debounce functions to handle the visibility of markers that are outside of the plotting area when the min/max bound changes and/or when a zoom action is performed (via chart cursor or scrollbar), to increase performance.

This property will be set when the chart is created and cannot be updated after that. It's recommended that this property should only be set to true for small datasets. When left undefined, will be treated as false.

Note: Applicable to line chart only.

Attribute
ignore-smooth-rendering-limit
Default value
false

ignoreViewExtent

Property
Type
boolean | undefined

This property will be effective when the component's view is provided or when the layer is set to a FeatureLayerView.

By default the queries made by the chart will consider the view's extent as the unique geometry filter applicable. This implies ignoring any geometry passed through the config (component.config.dataFilters) or the runtime filters (component.runtimeDataFilters).

Setting this property to false signals the queries to ignore the view's extent, whether an additional geometry filter is provided or not.

Attribute
ignore-view-extent
Default value
false

layer

Property
Type
FeatureLayerView | SupportedLayer | undefined

Used to perform queries. If the layer is a FeatureLayerView or if the layer and the view property are both provided, the queries will be executed client-side.

layerFieldsChangePolicy

Property
Type
LayerFieldsChangePolicy

Allows the chart to update automatically when the layer's fields change.

Applies when the field list (fields) in the feature layer is updated.

Attribute
layer-fields-change-policy
Default value
"refresh"

layerFilterChangePolicy

Property
Type
LayerFilterChangePolicy

Whether the chart should be refreshed when the layer's filter (definitionExpression) changes.

Attribute
layer-filter-change-policy
Default value
"refresh"

layerItemId

Property
Type
string | undefined

Layer item ID associated with the chart to be rendered. Can be used in conjunction with the chartIndex property.

If layerItemId is set without chartIndex, the first chart in the layer will be rendered.

Attribute
layer-item-id
Example
<arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2"></arcgis-chart>

layerRendererChangePolicy

Property
Type
LayerRendererChangePolicy

Allows the chart to update automatically when the layer's renderer changes.

Applies when the color match feature is enabled.

Note: If the property is set to ignore the chart will use the layer's renderer information when the data is updated.

Attribute
layer-renderer-change-policy
Default value
"refresh"

legendPosition

deprecated Property
Type
WebChartLegendPositions | undefined

Sets the legend's position on the chart.

Note: Not applicable to gauge.

Attribute
legend-position

legendValueLabelFormatter

Property
Type
PieChartLegendValueLabelFormatCallback | undefined

A callback function used to format the legend value labels. If the returned string contains HTML tags they will be interpreted as such. If provided, the formatter will be used if at least WebChartPieChartLegend.displayNumericValue or WebChartPieChartLegend.displayPercentage is true.

Note: Applicable to pie chart only.

legendVisibility

deprecated Property
Type
boolean | undefined

When true, the legend is visible on the chart.

Note: Not applicable to gauge.

Attribute
legend-visibility
Default value
false

loaderColors

Property
Type
LoaderColors | undefined

Defines the colors for the loader animation.

messageOverrides

Property
Type
Record<string, unknown> | undefined

Custom message overrides for the chart's strings.

model

Property
Type
ChartModel | WebChart | undefined

Provides an API to interact with the chart's configuration.

Note: This property has a union type of ChartModel | WebChart meaning a raw chart config object can be passed to it instead, however it is recommended to use a ChartModel instance whenever possible.

nullAsValid

Property
Type
boolean

Whether to consider a null statistic as valid. If set to false and the data has only null values, the chart's dataset will be considered empty:

  • The corresponding warning event will be sent
  • The "no data" message will be displayed (unless showUIMesssages is set to false)
Attribute
null-as-valid
Default value
false

placeholder

Property
Type
string | undefined

A placeholder string to provides a brief hint to the user indicating needed information for creating a chart.

Attribute
placeholder

queueChartCreation

Property
Type
boolean | undefined

Builds charts sequentially instead of rendering them all at once

Attribute
queue-chart-creation
Default value
false

replaceNoValueCategoryWithZero

Property
Type
boolean | undefined

When true, the chart's dataItems associated with empty (no value) categories (from only a Count aggregation) will be populated with 0s, via the completeDataForEmptyCategoriesWithZeros method.

Attribute
replace-no-value-category-with-zero
Default value
false

returnFeaturesExtent

Property
Type
boolean | undefined

When true, the features extent will be returned through the arcgisDataProcessComplete and arcgisSelectionComplete events payload. Applies only to:

  • Charts using an aggregation.
  • Data source using a feature layer compatible with envelope aggregation.

The extent (IExtent) is returned through a property called arcgis_charts_features_extent.

Note: Not applicable to gauge.

Attribute
return-features-extent
Default value
false

returnSelectionIndexes

Property
Type
boolean | undefined

When true, the selection indexes will be computed whenever a selection is made on or passed to the chart.

Note: Not applicable to gauge.

Attribute
return-selection-indexes
Default value
false

returnSelectionOIDs

Property
Type
boolean | undefined

When true, the object ids will be computed whenever a selection is made on or passed to the chart. Only considered for a data source using a feature layer.

Note: Not applicable to gauge.

Attribute
return-selection-oi-ds
Default value
false

rotation

deprecated Property
Type
boolean | undefined

When true, the chart is rotated 90 degrees so that the x-axis becomes vertical and the y-axis becomes horizontal.

Note: Applicable to bar chart, line chart, combo bar and line chart and box plot.

Attribute
rotation
Default value
false

runtimeDataFilters

Property
Type
WebChartDataFilters | undefined

Applies runtime data filters to the chart.

secondaryYAxisLabelFormatter

Property
Type
AxisLabelFormatCallback | undefined

A callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such. The property will be effective only if 3 axes are defined (dual axis chart).

Note: Not applicable to pie chart or gauge.

selectionData

Property
Type
SelectionData | undefined

When this property is set, it will apply a selection on the chart matching the provided selection.

Note: Not applicable to gauge.

selectionTheme

Property
Type
SelectionTheme | undefined

Used to provide a customized theme for the selected and non selected elements.

  • If no style is provided for the selected elements, a default selection is applied.
  • If no style is provided for the non selected elements, the chart's style is applied.

Note: Not applicable to gauge.

setTimeBinningInfoWhenNotProvided

Property
Type
boolean | undefined

When true, the series properties unit and size become optional and will be automatically set to values that fit the data set. Used when creating or updating a chart compatible with time binning.

Note: Only applicable to charts using the temporal binning feature (bar chart, line chart, combo bar and line chart, radar chart).

Attribute
set-time-binning-info-when-not-provided
Default value
false

showUIMessages

Property
Type
boolean | undefined

Whether to display or hide all UI messages (e.g. no data warnings, or when the logarithmic scale can't be applied to an axis when the data contains values <= 0).

Attribute
show-ui-messages
Default value
false

syncSelection

Property
Type
boolean

Whether to synchronize the selection between chart components from the same layer.

Attribute
sync-selection
Default value
false

syncSelectionsBetweenChartAndLayerViewPolicy

Property
Type
SyncSelectionsBetweenChartAndLayerViewPolicy

Determines whether the selections from the chart should be synchronized with the layer view and vice versa.

Attribute
sync-selections-between-chart-and-layer-view-policy
Default value
"disabled"

timeZone

Property
Type
MapView["timeZone"] | undefined

Used to set a custom time zone for the chart.

Attribute
time-zone

tooltipFormatter

Property
Type
ChartOptions["tooltipFormatter"] | undefined

A callback function used to format the tooltips. If the returned string contains HTML tags they will be interpreted as such.

Note: Not applicable to gauge.

updateSplitBySeries

Property
Type
MissingSplitBySeriesProps | undefined

Whether to update the series when the data updates while the chart uses a split-by field configuration.

If addMissingSeries is set to true the missing series will be added to cover the split-by values not referenced by the config. The default information from the property updateSplitBySeries.seriesTemplate will be applied to the new series.

Note: Applicable only to bar chart, line chart and box plot when a split-by field is used.

useAnimatedCharts

Property
Type
boolean | undefined

Enable animation on the chart.

Attribute
use-animated-charts
Default value
false

usePopupTemplateFieldsInfo

Property
Type
boolean | undefined

Allows the use of the fields alias from the layer.popupTemplate when rendering the field names on the chart (e.g. tooltips, axes, legend).

Attribute
use-popup-template-fields-info
Default value
false

view

Property
Type
MapView | SceneView | undefined

Used to access the feature layer view instance in order to perform client side queries.

viewTimeExtentChangePolicy

Property
Type
ViewTimeExtentChangePolicy

Whether the chart should be refreshed when the view's time extent changes.

Note: Not supported for histogram.

Attribute
view-time-extent-change-policy
Default value
"ignore"

xAxisLabelFormatter

Property
Type
AxisLabelFormatCallback | undefined

A callback function used to format the x-axis labels. If the returned string contains HTML tags they will be interpreted as such.

Note: Not applicable to pie chart.

yAxisLabelFormatter

Property
Type
AxisLabelFormatCallback | undefined

A callback function used to format the y-axis labels. If the returned string contains HTML tags they will be interpreted as such.

Note: Not applicable to pie chart or gauge.

Methods

MethodSignature
clearSelection(): Promise<void>
componentOnReady
inherited
componentOnReady(): Promise<this>
errorAlert(errorMessage?: string): Promise<void>
exportAsCSV(options?: CSVOptions): Promise<void>
exportAsImage(format?: DownloadableChartImagesTypes): Promise<void>
loadModel(): Promise<void>
notify(message?: string, heading?: string): Promise<void>
refresh(props?: { updateData?: boolean; resetAxesBounds?: boolean; }): Promise<void>
resetZoom(): Promise<void>
switchSelection(): Promise<void>

clearSelection

Method
Signature
clearSelection (): Promise<void>

Clears all selection on the chart.

Note: Not applicable to gauge.

Returns
Promise<void>

componentOnReady

inherited Method
Signature
componentOnReady (): Promise<this>
Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns
Promise<this>
Example
const arcgisChart = document.querySelector("arcgis-chart");
document.body.append(arcgisChart);
await arcgisChart.componentOnReady();
console.log("arcgis-chart is ready to go!");

errorAlert

Method
Signature
errorAlert (errorMessage?: string): Promise<void>

Triggers an alert to display an error message.

Parameters
ParameterTypeDescriptionRequired
errorMessage
Returns
Promise<void>

exportAsCSV

Method
Signature
exportAsCSV (options?: CSVOptions): Promise<void>

Export the current chart's data as a CSV file.

The Options object can contain the following properties:

  • columns: An array of column to include in the CSV file.
  • delimiter: The delimiter to use in the CSV file. Default is ,.
  • includeHeader: Whether to include the header row in the CSV file. Default is true.
  • quoteAll: Whether to quote all values in the CSV file. Default is false.
  • locale: The locale to use when formatting the CSV file. Default is en.
    • Locale supported are: "ar", "ar-u-nu-latn", "bs", "bg", "ca", "cs", "da", "de", "el", "en", "en-US", "es", "et", "fi", "fr", "he", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "no", "nl", "pl", "pt-BR", "pt-PT", "ro", "ru", "sr", "sl", "sk", "sv", "th", "tr", "uk", "vi", "zh-CN", "zh-HK", "zh-TW"

Note: The chart types supported by this method are:

  • Bar chart
  • Box plot
  • Combo bar and line chart
  • Histogram
  • Line chart
  • Pie chart
Parameters
ParameterTypeDescriptionRequired
options
Returns
Promise<void>

exportAsImage

Method
Signature
exportAsImage (format?: DownloadableChartImagesTypes): Promise<void>

Exports the current chart as an image. Default format is png.

  • Alternative formats supported are: jpeg and svg.
Parameters
ParameterTypeDescriptionRequired
format
Returns
Promise<void>

loadModel

Method
Signature
loadModel (): Promise<void>

Returns a promise that resolves when the chart model is fully loaded.

Returns
Promise<void>

notify

Method
Signature
notify (message?: string, heading?: string): Promise<void>

Notify method allows passing external messages to the chart component. It can be used to pass validation or information messages. In a situation where a config update is overriding your notification modal, consider waiting for the arcgisUpdateComplete event.

Parameters
ParameterTypeDescriptionRequired
message

The message to display in the notification panel.

heading

The heading to display in the notification panel.

Returns
Promise<void>

refresh

Method
Signature
refresh (props?: { updateData?: boolean; resetAxesBounds?: boolean; }): Promise<void>

Re-render the chart.

Parameters
ParameterTypeDescriptionRequired
props
{ updateData?: boolean; resetAxesBounds?: boolean; }

Indicates whether to fetch new data. Default: true.

Returns
Promise<void>

resetZoom

Method
Signature
resetZoom (): Promise<void>

Resets the chart zoom to bring it back to full extent

Note: Applicable to XY charts only.

Returns
Promise<void>

switchSelection

Method
Signature
switchSelection (): Promise<void>

Switches the selection on the chart.

Note: Not applicable to gauge.

Returns
Promise<void>

Events

arcgisAxesMinMaxChange

Event
arcgisAxesMinMaxChange: CustomEvent<AxesMinMaxChangePayload>

Event triggered once the chart axes min/max values are computed.

bubbles composed cancelable

arcgisBadDataWarningRaise

Event
arcgisBadDataWarningRaise: CustomEvent<DataWarningObject>

Event triggered when an error is detected with the data set.

bubbles composed cancelable

arcgisChartNotFoundWarning

Event
arcgisChartNotFoundWarning: CustomEvent<string>

Event triggered when the chart is not found for the given chartIndex property.

bubbles composed cancelable

arcgisConfigChange

Event
arcgisConfigChange: CustomEvent<{ newConfig: WebChart | undefined; oldConfig: WebChart | undefined; functionCalled: string | undefined; }>

Event triggered when the chart config is changed.

bubbles composed cancelable

arcgisDataFetchComplete

Event
arcgisDataFetchComplete: CustomEvent<WebChartDataTypes>

Event triggered once the chart data has been fetched but not yet fully processed.

For instance it can be useful to see all the slices before they get grouped into an 'other' slice during the post-processing step.

Note: Applicable to pie chart only.

bubbles composed cancelable

arcgisDataProcessComplete

Event
arcgisDataProcessComplete: CustomEvent<DataProcessCompletePayload>

Event triggered once the chart data has been processed.

bubbles composed cancelable

arcgisDataProcessError

Event
arcgisDataProcessError: CustomEvent<void>

Event triggered when an error occurred while fetching of processing the data for the chart.

bubbles composed cancelable

arcgisInvalidConfigWarningRaise

Event
arcgisInvalidConfigWarningRaise: CustomEvent<DataWarningObject>

Event triggered when an invalid configuration is detected.

bubbles composed cancelable

arcgisLegendItemVisibilityChange

Event
arcgisLegendItemVisibilityChange: CustomEvent<LegendItemVisibilityChangePayload>

Event triggered once a legend item visibility has been changed.

bubbles composed cancelable

arcgisNoRenderPropChange

Event
arcgisNoRenderPropChange: CustomEvent<NoRenderPropChangePayload>

Event triggered when a no-render prop is changed.

bubbles composed cancelable

arcgisRenderingComplete

Event
arcgisRenderingComplete: CustomEvent<void>

Event triggered once the chart rendering is complete.

bubbles composed cancelable

arcgisRuntimeError

Event
arcgisRuntimeError: CustomEvent<void>

Event triggered when an error occurred that prevents the chart from being created or updated.

bubbles composed cancelable

arcgisSelectionComplete

Event
arcgisSelectionComplete: CustomEvent<SelectionCompletePayload>

Event triggered when a selection is applied to the chart.

bubbles composed cancelable

arcgisSeriesColorChange

Event
arcgisSeriesColorChange: CustomEvent<SeriesColorChangePayload>

Event triggered once the chart series color have been assigned.

bubbles composed cancelable

arcgisSeriesOrder

Event
arcgisSeriesOrder: CustomEvent<string[]>

Event carrying the series id as they have been sorted following the orderOptions instructions.

bubbles composed cancelable

arcgisUpdateComplete

Event
arcgisUpdateComplete: CustomEvent<ValidationStatus>

Event triggered once the chart is updated.

bubbles composed cancelable

Slots

NameDescription

Slot for adding a charts-action-bar component or calcite-action-bar.