Skip to main content
ScatterChart plots data as individual points on a cartesian plane, positioned by their x_axis and y_axis values. Where bar charts compare categories and line charts show change over time, scatter charts reveal relationships between two continuous variables — whether they’re correlated, clustered, or independent.

​
Basic Usage

Every scatter chart needs three things: the data, a series definition, and the two axis mappings. The data is a list of dicts where each dict is a point. x_axis and y_axis name the fields that position each point on the chart. The data_key on ChartSeries is an identifier for the series — it controls color and legend display.

​
Multiple Series

To plot multiple groups on the same axes, add a _series field to each data point that matches the data_key of its series. Each series gets its own color from the theme palette and appears as a separate entry in the legend. This is useful for comparing distributions across categories — here, two classes of students plotted by study hours vs. test scores.

​
Bubble Chart

Set z_axis to a numeric field to scale each point’s size proportionally, turning the scatter into a bubble chart. This encodes a third dimension directly in the visualization — larger bubbles represent higher values of the z-axis field. Useful for comparing entities that have three measurable attributes.

​
API Reference

ScatterChart Parameters

​
data
list[dict] | str
required
Data as a list of dicts, or a {{ field }} interpolation reference. For multiple series, include a _series field in each dict matching the series data_key.
​
series
list[ChartSeries]
required
Series definitions — each becomes a group of scatter points on the chart.
​
x_axis
str
required
Data key for x-axis numeric values.
​
y_axis
str
required
Data key for y-axis numeric values.
​
z_axis
str | None
default:"None"
Data key for bubble size. When set, point radii scale proportionally to this field’s values.
​
height
int
default:"300"
Chart height in pixels.
​
show_legend
bool
default:"False"
Show a legend below the chart.
​
show_tooltip
bool
default:"True"
Show tooltips on hover.
​
show_grid
bool
default:"True"
Show cartesian grid lines.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

ChartSeries Parameters

​
data_key
str
required
Identifier for the series — used for color mapping and legend display. For multi-series scatter charts, this must match the _series values in the data.
​
label
str | None
default:"None"
Display label for legends and tooltips. Defaults to the data_key value.
​
color
str | None
default:"None"
CSS color override. By default, colors cycle through the theme’s chart palette (--chart-1 through --chart-5).

​
Protocol Reference

ScatterChart
{
  "type": "ScatterChart",
  "data": "dict[] | string (required)",
  "series": "[ChartSeries] (required)",
  "xAxis": "string (required)",
  "yAxis": "string (required)",
  "zAxis?": "string",
  "height?": "300",
  "showLegend?": false,
  "showTooltip?": true,
  "showGrid?": true,
  "cssClass?": "string"
}
ChartSeries
{
  "dataKey": "string (required)",
  "label?": "string",
  "color?": "string"
}
For the complete protocol schema, see ScatterChart, ChartSeries.