import "@arcgis/charts-components/components/arcgis-chart";- Inheritance:
- ArcgisChart→
PublicLitElement
- 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
-
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
| Property | Attribute | Type |
|---|---|---|
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 | ||
| ChartOptions["tooltipFormatter"] | undefined | |
| ||
use-animated-charts | ||
use-popup-template-fields-info | ||
| ||
view-time-extent-change-policy | ||
| ||
|
actionMode
- 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
- 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
- Type
- DOMContainerAria
- Since
- ArcGIS Maps SDK for JavaScript 5.0
The ARIA attributes for the chart.
autoDestroyDisabled
- 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
autoInverseDataLabelTextColor
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
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
- 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
- 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
- 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
- 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.
enableConfiguration
- 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
errorPolicy
- 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"
hideEmptySeries
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
ignoreSmoothRenderingLimit
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
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
- 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.
layerItemId
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
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
- Type
- WebChartLegendPositions | undefined
Sets the legend's position on the chart.
Note: Not applicable to gauge.
- Attribute
- legend-position
legendValueLabelFormatter
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.
model
- 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
- 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
showUIMesssagesis set tofalse)
- Attribute
- null-as-valid
- Default value
- false
returnFeaturesExtent
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
runtimeDataFilters
- Type
- WebChartDataFilters | undefined
Applies runtime data filters to the chart.
secondaryYAxisLabelFormatter
- 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
- 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
- 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
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
syncSelection
- Type
- boolean
Whether to synchronize the selection between chart components from the same layer.
- Attribute
- sync-selection
- Default value
- false
tooltipFormatter
- 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
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.
xAxisLabelFormatter
- 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
- 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
| Method | Signature |
|---|---|
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> |
componentOnReady
- Signature
-
componentOnReady (): Promise<this>
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!"); exportAsCSV
- 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 istrue.quoteAll: Whether to quote all values in the CSV file. Default isfalse.locale: The locale to use when formatting the CSV file. Default isen.- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| options | | |
notify
- 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.
Events
| Name | Type |
|---|---|
arcgisAxesMinMaxChange
arcgisAxesMinMaxChange: CustomEvent<AxesMinMaxChangePayload> Event triggered once the chart axes min/max values are computed.
arcgisBadDataWarningRaise
arcgisBadDataWarningRaise: CustomEvent<DataWarningObject> Event triggered when an error is detected with the data set.
arcgisChartNotFoundWarning
arcgisChartNotFoundWarning: CustomEvent<string> Event triggered when the chart is not found for the given chartIndex property.
arcgisConfigChange
arcgisConfigChange: CustomEvent<{
newConfig: WebChart | undefined;
oldConfig: WebChart | undefined;
functionCalled: string | undefined;
}> Event triggered when the chart config is changed.
arcgisDataFetchComplete
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.
arcgisDataProcessComplete
arcgisDataProcessComplete: CustomEvent<DataProcessCompletePayload> Event triggered once the chart data has been processed.
arcgisDataProcessError
arcgisDataProcessError: CustomEvent<void> Event triggered when an error occurred while fetching of processing the data for the chart.
arcgisInvalidConfigWarningRaise
arcgisInvalidConfigWarningRaise: CustomEvent<DataWarningObject> Event triggered when an invalid configuration is detected.
arcgisLegendItemVisibilityChange
arcgisLegendItemVisibilityChange: CustomEvent<LegendItemVisibilityChangePayload> Event triggered once a legend item visibility has been changed.
arcgisNoRenderPropChange
arcgisNoRenderPropChange: CustomEvent<NoRenderPropChangePayload> Event triggered when a no-render prop is changed.
arcgisRenderingComplete
arcgisRenderingComplete: CustomEvent<void> Event triggered once the chart rendering is complete.
arcgisRuntimeError
arcgisRuntimeError: CustomEvent<void> Event triggered when an error occurred that prevents the chart from being created or updated.
arcgisSelectionComplete
arcgisSelectionComplete: CustomEvent<SelectionCompletePayload> Event triggered when a selection is applied to the chart.
arcgisSeriesColorChange
arcgisSeriesColorChange: CustomEvent<SeriesColorChangePayload> Event triggered once the chart series color have been assigned.
arcgisSeriesOrder
arcgisSeriesOrder: CustomEvent<string[]> Event carrying the series id as they have been sorted following the orderOptions instructions.
arcgisUpdateComplete
arcgisUpdateComplete: CustomEvent<ValidationStatus> Event triggered once the chart is updated.
Slots
| Name | Description |
|---|---|
| Slot for adding a |