Overview
Both Scatter and Bubble charts are members of the Chart block's distribution chart family. They share an X/Y cartesian plane but differ in their data bindings:
Scatter: Each data point is plotted by its X and Y values. Category is used only for color grouping.
Bubble: Like Scatter, but a third field drives the size (radius) of each point, making it a three-variable plot.
Tip: Both types are configured via Chart Type = Scatter. To switch to a bubble chart, simply bind the Size field in the series configuration — that activates the bubble rendering. Without a Size binding, all points render at equal size (scatter mode).
Required Data Shape
Each record should represent one data point. Required fields:
A numeric field for the X position
A numeric field for the Y position
A string/category field for the Group by (used for color-coding series)
Bubble only: A numeric field for Size (bubble radius)
Sample scatter data (sales performance)
[ { "rep": "Alice", "calls": 120, "revenue": 45000, "deal_size": 375 }, { "rep": "Bob", "calls": 95, "revenue": 32000, "deal_size": 337 }, { "rep": "Carol", "calls": 140, "revenue": 58000, "deal_size": 414 }, { "rep": "David", "calls": 80, "revenue": 28000, "deal_size": 350 } ]
Bind calls → X, revenue → Y, rep → Group by. For a bubble: also bind deal_size → Size.
Content Properties
| Property | Description |
| Data Source | The array of records to plot as points. |
| X Axis → Value | The numeric field to use as the horizontal position of each point. |
| X Axis → Label / Format | Axis label and number format for the X axis tick labels. |
| Y Axis → Value | The numeric field to use as the vertical position of each point. |
| Y Axis → Label / Format | Axis label and number format for the Y axis tick labels. |
| Group by | The field whose distinct values determine point color. Each unique value becomes a separate color group (series). |
| Series → Size | Optional (optional) A numeric field that drives the radius of each bubble. Binding this activates bubble mode. |
| Series → Label | Display name for the series used in tooltips and legend. |
| Tooltip | Customizable header and body for hover tooltips. Useful to show a point's label (e.g., rep name) and all three dimensions. |
Appearance Properties
| Property | Options / Default | Description |
| X Axis → Min / Max | numeric | Manually set the visible range of the X axis. Useful for zooming in or aligning multiple charts. |
| Y Axis → Min / Max | numeric | Manually set the visible range of the Y axis. |
| Chart Colours | color per group | Assign colors to each Group by value. The same color logic used in Line and Bar charts. |
| Legend Position | top, right, bottom, left, remove | Shows which color maps to which Group by value. |
| Threshold | one or more threshold configs | Horizontal reference lines at a fixed Y value — useful for marking a target or threshold on the Y axis. |
| Scroller / Range Slider | toggle | Adds a range slider below the X axis for zooming into a subset of the X range. |
| styles | style set | Block dimensions, padding, overflow. |
Events & Methods
| Event | Description |
| On Data Point Click | Fires when a point (or bubble) is clicked. The payload is the full record for that point. Use to open a detail drawer or filter other blocks. |
Scatter vs Bubble Comparison
| Feature | Scatter | Bubble |
| X field | Numeric | Numeric |
| Y field | Numeric | Numeric |
| Size field | Not used (all points equal size) | Numeric — drives bubble radius |
| Group by | String (color grouping) | String (color grouping) |
| Best for | Correlation, outlier detection | Three-variable comparison (e.g., region × revenue × volume) |
Behavior & Gotchas
⚠ X and Y axes must be numeric
Scatter and Bubble charts require numeric X and Y fields. If you bind a string field to X or Y, the block treats values as categories and produces unexpected axis spacing. Use Category-axis bar charts for string-vs-numeric comparisons.
⚠ Bubble size is relative, not absolute
The Size field scales bubble radii proportionally within the chart. A value of 100 does not mean a 100px bubble — it means the largest-value bubble fills the chart's max radius and others are scaled relative to it. This means the same bubble chart will look different if the max Size value changes.
⚠ Overlapping points are not automatically jittered
Points that share the same X/Y values will overlap completely. Consider adding a small amount of jitter in your data query, or using a Heatmap for dense distributions.
⚠ Tooltip is the primary way to label points
Scatter charts do not show point labels by default. Configure the Tooltip to include the identifying field (e.g., representative name) so users can hover to identify points.
Common Patterns
Sales Rep Performance Matrix (Bubble)
Bind dimensions: X = number of calls, Y = total revenue, Size = average deal size, Group by = team or region.
Configure tooltip: In the Tooltip, include the rep name, all three metrics, and a calculated conversion rate so users get full context on hover.
Add a threshold: Add a Threshold at the revenue target value to visually split reps above and below quota.
Correlation Explorer (Scatter + Drill-Down)
Bind the dimensions: Bind the two continuous fields you want to correlate to X and Y. Use Group by to color-code by category (e.g., product line).
Wire up click drill-down: On On Data Point Click, store the clicked record in a page variable. Display a details panel next to the chart bound to that variable.
Frequently Asked Questions
How do I enable bubble mode (variable-size points)?
Set Chart Type = Scatter, then bind a numeric field to the Size property in the series configuration. As soon as a Size field is bound, the chart automatically switches to bubble rendering mode — all points become circles sized relative to that field's value.
My points all render at the same position even though X and Y values differ. Why?
Verify that the X and Y fields you're binding contain numeric values, not strings. If a numeric field is stored as a string in your data source, the chart may not parse it correctly. Also check that you are binding to the field's value, not a display-formatted label string.
Can I draw a best-fit regression line on the scatter chart?
Not natively. To add a trend line, calculate the regression coordinates server-side and bind the result as a separate Line or Scatter series overlaid on the same chart. The Chart block does not compute regression lines automatically.
How do I control the maximum bubble size?
Bubble size is determined by the ratio of each point's Size value to the maximum Size value in the dataset. There is no direct "max radius in pixels" setting. To keep bubble sizes manageable, cap the Size values in your data query, or normalize them to a fixed range before binding.