ScatterChart API

API reference docs for the React ScatterChart component. Learn about the props, CSS, and other APIs of this exported module.

Demos

For examples and details on the usage of this React component, visit the component demo pages:

Import

import { ScatterChart } from '@mui/x-charts/ScatterChart';
// or
import { ScatterChart } from '@mui/x-charts';
// or
import { ScatterChart } from '@mui/x-charts-pro';

Learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
series*	Array<object>	-	The series to display in the scatter chart. An array of ScatterSeriesType objects.
axisHighlight	{ x?: 'band' \| 'line' \| 'none', y?: 'band' \| 'line' \| 'none' }	{ x: 'none', y: 'none' }	The configuration of axes highlight. See highlighting docs for more details.
bottomAxis	object \| string	xAxisIds[0] The id of the first provided axis	Indicate which axis to display the bottom of the charts. Can be a string (the id of the axis) or an object `ChartsXAxisProps`.
colors	Array<string> \| func	blueberryTwilightPalette	Color palette used to colorize multiple series.
dataset	Array<object>	-	An array of objects that can be used to populate series and axes data using their `dataKey` property.
disableAxisListener	bool	false	If `true`, the charts will not listen to the mouse move event. It might break interactive features, but will improve performance.
disableVoronoi	bool	false	If true, the interaction will not use the Voronoi cell and fall back to hover events.
grid	{ horizontal?: bool, vertical?: bool }	-	Option to display a cartesian grid in the background.
height	number	-	The height of the chart in px. If not defined, it takes the height of the parent element.
hideLegend	bool	-	If `true`, the legend is not rendered.
highlightedItem	{ dataIndex?: number, seriesId?: number \| string }	-	The item currently highlighted. Turns highlighting into a controlled prop.
leftAxis	object \| string	yAxisIds[0] The id of the first provided axis	Indicate which axis to display the left of the charts. Can be a string (the id of the axis) or an object `ChartsYAxisProps`.
loading	bool	false	If `true`, a loading overlay is displayed.
margin	{ bottom?: number, left?: number, right?: number, top?: number }	object Depends on the charts type.	The margin between the SVG and the drawing area. It's used for leaving some space for extra information such as the x- and y-axis or legend. Accepts an object with the optional properties: `top`, `bottom`, `left`, and `right`.
onHighlightChange	func	-	The callback fired when the highlighted item changes. Signature:`function(highlightedItem: HighlightItemData \| null) => void` `highlightedItem` The newly highlighted item.
onItemClick	func	-	Callback fired when clicking on a scatter item. Signature:`function(event: MouseEvent, scatterItemIdentifier: ScatterItemIdentifier) => void` `event` The mouse event recorded on the `<svg/>` element if using Voronoi cells. Or the Mouse event from the scatter element, when `disableVoronoi=true`. `scatterItemIdentifier` The scatter item identifier.
resolveSizeBeforeRender	bool	false	The chart will try to wait for the parent container to resolve its size before it renders for the first time. This can be useful in some scenarios where the chart appear to grow after the first render, like when used inside a grid.
rightAxis	object \| string	null	Indicate which axis to display the right of the charts. Can be a string (the id of the axis) or an object `ChartsYAxisProps`.
skipAnimation	bool	-	If `true`, animations are skipped. If unset or `false`, the animations respects the user's `prefers-reduced-motion` setting.
slotProps	object	{}	The props used for each component slot.
slots	object	{}	Overridable component slots. See Slots API below for more details.
tooltip	{ axisContent?: elementType, classes?: object, itemContent?: elementType, slotProps?: object, slots?: object, trigger?: 'axis' \| 'item' \| 'none' }	{ trigger: 'item' }	The configuration of the tooltip. See tooltip docs for more details.
topAxis	object \| string	null	Indicate which axis to display the top of the charts. Can be a string (the id of the axis) or an object `ChartsXAxisProps`.
voronoiMaxRadius	number	-	Defines the maximal distance between a scatter point and the pointer that triggers the interaction. If `undefined`, the radius is assumed to be infinite.
width	number	-	The width of the chart in px. If not defined, it takes the width of the parent element.
xAxis	Array<{ classes?: object, colorMap?: { colors: Array<string>, type: 'ordinal', unknownColor?: string, values?: Array<Date \| number \| string> } \| { color: Array<string> \| func, max?: Date \| number, min?: Date \| number, type: 'continuous' } \| { colors: Array<string>, thresholds: Array<Date \| number>, type: 'piecewise' }, data?: array, dataKey?: string, disableLine?: bool, disableTicks?: bool, domainLimit?: 'nice' \| 'strict' \| func, fill?: string, hideTooltip?: bool, id?: number \| string, label?: string, labelFontSize?: number, labelStyle?: object, max?: Date \| number, min?: Date \| number, position?: 'bottom' \| 'top', reverse?: bool, scaleType?: 'band' \| 'linear' \| 'log' \| 'point' \| 'pow' \| 'sqrt' \| 'time' \| 'utc', slotProps?: object, slots?: object, stroke?: string, sx?: Array<func \| object \| bool> \| func \| object, tickFontSize?: number, tickInterval?: 'auto' \| array \| func, tickLabelInterval?: 'auto' \| func, tickLabelPlacement?: 'middle' \| 'tick', tickLabelStyle?: object, tickMaxStep?: number, tickMinStep?: number, tickNumber?: number, tickPlacement?: 'end' \| 'extremities' \| 'middle' \| 'start', tickSize?: number, valueFormatter?: func }>	-	The configuration of the x-axes. If not provided, a default axis config is used. An array of AxisConfig objects.
yAxis	Array<{ classes?: object, colorMap?: { colors: Array<string>, type: 'ordinal', unknownColor?: string, values?: Array<Date \| number \| string> } \| { color: Array<string> \| func, max?: Date \| number, min?: Date \| number, type: 'continuous' } \| { colors: Array<string>, thresholds: Array<Date \| number>, type: 'piecewise' }, data?: array, dataKey?: string, disableLine?: bool, disableTicks?: bool, domainLimit?: 'nice' \| 'strict' \| func, fill?: string, hideTooltip?: bool, id?: number \| string, label?: string, labelFontSize?: number, labelStyle?: object, max?: Date \| number, min?: Date \| number, position?: 'left' \| 'right', reverse?: bool, scaleType?: 'band' \| 'linear' \| 'log' \| 'point' \| 'pow' \| 'sqrt' \| 'time' \| 'utc', slotProps?: object, slots?: object, stroke?: string, sx?: Array<func \| object \| bool> \| func \| object, tickFontSize?: number, tickInterval?: 'auto' \| array \| func, tickLabelInterval?: 'auto' \| func, tickLabelPlacement?: 'middle' \| 'tick', tickLabelStyle?: object, tickMaxStep?: number, tickMinStep?: number, tickNumber?: number, tickPlacement?: 'end' \| 'extremities' \| 'middle' \| 'start', tickSize?: number, valueFormatter?: func }>	-	The configuration of the y-axes. If not provided, a default axis config is used. An array of AxisConfig objects.
zAxis	Array<{ colorMap?: { colors: Array<string>, type: 'ordinal', unknownColor?: string, values?: Array<Date \| number \| string> } \| { color: Array<string> \| func, max?: Date \| number, min?: Date \| number, type: 'continuous' } \| { colors: Array<string>, thresholds: Array<Date \| number>, type: 'piecewise' }, data?: array, dataKey?: string, id?: string, max?: number, min?: number }>	-	The configuration of the z-axes.

The ref is forwarded to the root element.

Theme default props

You can use MuiScatterChart to change the default props of this component with the theme.

Slots

Slot name	Default component	Description
axisContent	`DefaultChartsAxisTooltipContent`	Custom component for displaying tooltip content when triggered by axis event.
axisLabel	`ChartsText`	Custom component for axis label.
axisLine	`'line'`	Custom component for the axis main line.
axisTick	`'line'`	Custom component for the axis tick.
axisTickLabel	`ChartsText`	Custom component for tick label.
itemContent	`DefaultChartsItemTooltipContent`	Custom component for displaying tooltip content when triggered by item event.
legend	`DefaultChartsLegend`	Custom rendering of the legend.
loadingOverlay	`ChartsLoadingOverlay`	Overlay component rendered when the chart is in a loading state.
noDataOverlay	`ChartsNoDataOverlay`	Overlay component rendered when the chart has no data to display.
popper	`ChartsTooltipRoot`	Custom component for the tooltip popper.
scatter

Source code

If you did not find the information in this page, consider having a look at the implementation of the component for more detail.