AG Studio Launch Week šŸš€šŸš€šŸš€ 28 Sep - 2 Oct 2026 šŸš€šŸš€šŸš€ Join now

JavaScript ChartsScatter Series

Version 14.2.0

A Scatter Series identifies the correlation between values across two categories, and can highlight outliers and gaps in the data.

Simple Scatter Copy Link

To create a Scatter Series use the 'scatter' series type.

{
    series: [
        {
            type: 'scatter',
            title: 'Male',
            xKey: 'height',
            xName: 'Height',
            yKey: 'weight',
            yName: 'Weight',
        },
    ],
}

In this configuration:

  • xKey defines the numerical values for the x-axis, and is mapped by default to a Number.
  • yKey provides the numerical values for the y-axis, and is mapped by default to a Number Axis.
  • xName and yName are optional and configure display names, reflected in Tooltips.
  • title is optional and is used in the Tooltip Titles and Legend Items.

Markers Copy Link

It is possible to customise the fill, stroke and shape of the markers used in the Scatter Series.

{
    series: [
        {
            //...
            shape: 'square',
            fill: '#e36f6ab5',
            stroke: '#9f4e4a',
        },
    ],
}

In the above example, the 'females' series uses 'circle' markers and the 'male' series uses 'square' markers.

Please see the Series Markers page for more information or the API Reference for a list of all available styling options.

Labels Copy Link

To show labels for a Scatter Series set the label.enabled config of a series to true and specify which key should be used to fetch the label values.

Scatter Series label placement is constrained so that:

  • labels don't overlap any markers
  • labels don't overlap other labels

If these constraints are not satisfied, a label is not placed.

Try opening the above example in a larger window to see that more labels are placed as the chart gets bigger. You can also try changing the size of the markers and the font size of the labels to see how that affects label placement.

See Series Labels: Collision Avoidance for more details.

Colour Scale Copy Link

Supply a colorKey to colour each marker by a data value, and customise the colouring via colorScale.

See the Colour Scale page for the full configuration reference including discrete bins, named stops and legend customisation.

Large Datasets Copy Link

By default, a maximum of 2000 markers per series are rendered. Items beyond this limit are aggregated to improve performance whilst maintaining the same visual appearance. Use maxRenderedItems to increase this limit if needed.

See Large Dataset Interactivity for more details.

Scatter Chart Examples Copy Link

See more Scatter Chart examples in the AG Charts Gallery.

API Reference Copy Link

Properties available on the AgScatterSeriesOptions interface.

type required 'scatter'
Configuration for the Scatter Series.
xKey required DatumKey
The key to use to retrieve x-values from the data.
yKey required DatumKey
The key to use to retrieve y-values from the data.
errorBar AgErrorBarOptions
Configuration for the Error Bars.
id string default: auto-generated value
Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
context ContextDefault
Context object to use in callbacks.
data DatumDefault[]
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean
Whether to display the series.
cursor string
The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
selection AgSelectionOptions
Configuration for data selection.
nodeClickRange InteractionRange
Range from a node that a click triggers the listener.
showInLegend boolean
Whether to include the series in the legend.
listeners AgSeriesListeners
A map of event names to event listeners.
xKeyAxis string default: 'x'
The key of the x-axis to which this series is bound.
yKeyAxis string default: 'y'
The key of the y-axis to which this series is bound.
labelKey DatumKey
The key to use to retrieve values from the data to use as labels for the markers.
colorKey DatumKey
The key to use to retrieve colour values from the data. This value (along with `colorScale` config) will be used to determine the marker colour.
xName string
A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yName string
A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
labelName string
A human-readable description of the label values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
colorName string
A human-readable description of the colour values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
legendItemName string
The text to display in the legend for this series. If supplied, matching items with the same value will be toggled together.
maxRenderedItems number default: 2000
Determines the largest number of items that can be rendered at once. If there are more items, they will be aggregated to resemble similar visual appearance.
title string
The title to use for the series. Defaults to `yName` if it exists, or `yKey` if not.
label AgScatterSeriesLabel
Configuration for the labels shown on top of data points.
tooltip AgSeriesTooltip
Series-specific tooltip configuration.
styler Styler
Function used to return formatting for entire series, based on the given parameters.
itemStyler Styler
Function used to return formatting for individual markers, based on the supplied information.
highlight AgMultiSeriesHighlightOptions
Configuration for highlighting when a series or legend item is hovered over.
colorScale AgColorScale
Configuration for colour scale with fills, domain, and mode.
showInMiniChart boolean
Whether to include the series in the Mini Chart.
size PixelSize
The size in pixels of the markers.
shape AgMarkerShape
The shape to use for the markers. You can also supply a custom marker by providing a `AgMarkerShapeFn` function.
fill AgColorType
The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
fillOpacity Opacity
The opacity of the fill colour.
stroke AgCssColorOrRef
The colour for the stroke.
strokeWidth PixelSize
The width of the stroke in pixels.
strokeOpacity Opacity
The opacity of the stroke colour.
lineDash PixelSize[]
An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.