Charts - Scatter

Scatter charts express the relation between two variables, using points in a surface.

Basics

Scatter chart series should contain a data property containing an array of objects. Those objects require the x and y properties. With an optional id property if more optimization is needed.

Series A
Series B

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
    },
  ]}
/>

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
    },
  ]}
/>

Press Enter to start editing

Using a dataset

If your data is stored in an array of objects, you can use the dataset helper prop. It accepts an array of objects such as dataset={[{a: 1, b: 32, c: 873}, {a: 2, b: 41, c: 182}, ...]}.

You can reuse this data when defining the series. The scatter series work a bit differently than in other charts. You need to specify the datasetKeys properties which is an object that requires the x and y keys. With an optional id and z keys if needed.

Series A
Series B

<ScatterChart
  dataset={dataset}
  series={[
    { datasetKeys: { id: 'version', x: 'a1', y: 'a2' }, label: 'Series A' },
    { datasetKeys: { id: 'version', x: 'b1', y: 'b2' }, label: 'Series B' },
  ]}
  {...chartSetting}
/>

<ScatterChart
  dataset={dataset}
  series={[
    { datasetKeys: { id: 'version', x: 'a1', y: 'a2' }, label: 'Series A' },
    { datasetKeys: { id: 'version', x: 'b1', y: 'b2' }, label: 'Series B' },
  ]}
  {...chartSetting}
/>

Press Enter to start editing

Interaction

Since scatter elements can be small, interactions do not require hovering exactly over an element. When the pointer is in the drawing area, the closest scatter element will be used for interactions (tooltip or highlights). To do so, the chart computes Voronoi cells which map the pointer position to the closest element.

You can define a maximal radius with the voronoiMaxRadius prop. If the distance with the pointer is larger than this radius, no item will be selected. Or set the disableVoronoi prop to true to trigger interactions only when hovering exactly over an element instead of Voronoi cells.

Series A
Series B

max radius

disableVoronoiundefined radius

Click event

Scatter Chart provides an onItemClick handler for handling clicks on specific scatter items. It has the following signature.

const onItemClick = (
  event, // The mouse event.
  params, // An object that identifies the clicked elements.
) => {};

Click on the chart

// The data will appear here

If disableVoronoi=true, users need to click precisely on the scatter element, and the mouse event will come from this element.

Otherwise, the click behavior will be the same as defined in the interaction section and the mouse event will come from the svg component.

Styling

Color scale

As with other charts, you can modify the series color either directly, or with the color palette.

You can also modify the color by using axes colorMap which maps values to colors. The scatter charts use by priority:

The z-axis color
The y-axis color
The x-axis color
The series color

The z-axis is a third axis that allows to customize scatter points independently from their position. It can be provided with zAxis props.

The value to map can either come from the z property of series data, or from the zAxis data. Here are three ways to set z value to 5.

<ScatterChart
  // First option
  series={[{ data: [{ id: 0, x: 1, y: 1, z: 5 }] }]}
  // Second option
  zAxis={[{ data: [5] }]}
  // Third option
  dataset={[{ price: 5 }]}
  zAxis={[{ dataKey: 'price' }]}
/>

Learn more about the colorMap properties in the Styling docs.

x-axis colorMap

y-axis colorMap

z-axis colorMap

<ScatterChart
  /* ... */
  series={[{ data: data.map(point => ({...point, z: point.x + point.y})) }]}
  xAxis={[{
    colorMap: {
      type: 'piecewise',
      thresholds: [-1.5, 0, 1.5],
      colors: ['#d01c8b', '#f1b6da', '#b8e186', '#4dac26'],
    }
  }]}
  yAxis={[{}]}
  zAxis={[{}]}
/>

Grid

You can add a grid in the background of the chart with the grid prop.

See Axis—Grid documentation for more information.

Series A
Series B

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
    },
  ]}
  grid={{ vertical: true, horizontal: true }}
/>

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
    },
  ]}
  grid={{ vertical: true, horizontal: true }}
/>

Press Enter to start editing

CSS 🚧

Shape 🚧

Size

You can customize the size of points in a scatter chart using the markerSize prop of every series. For circles, the markerSize is the radius of the point in pixels.

Series A
Series B

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
      markerSize: 8,
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
      markerSize: 4,
    },
  ]}
/>

<ScatterChart
  width={600}
  height={300}
  series={[
    {
      label: 'Series A',
      data: data.map((v) => ({ x: v.x1, y: v.y1, id: v.id })),
      markerSize: 8,
    },
    {
      label: 'Series B',
      data: data.map((v) => ({ x: v.x1, y: v.y2, id: v.id })),
      markerSize: 4,
    },
  ]}
/>

Press Enter to start editing

Plot Customization

You can customize the plotting of the data in a scatter chart by providing custom components as children of the ScatterChart component.

A scatter chart's series can be accessed through the useScatterSeries hook. This hook returns the order of the series and information about the series themselves, including their data points, color, etc.

See Custom components to learn how to further customize your charts.

Open
Closed

<ScatterChart series={series} width={500} height={300}>
  <LinkPoints seriesId="s1" />
  <LinkPoints seriesId="s2" close />
</ScatterChart>

<ScatterChart series={series} width={500} height={300}>
  <LinkPoints seriesId="s1" />
  <LinkPoints seriesId="s2" close />
</ScatterChart>

Press Enter to start editing

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.