Scatter
A scatter places one point per row from two quantitative fields. encoding.x is the horizontal measure. encoding.y is the vertical measure. A third field on encoding.size turns the same chart into a bubble reading.
When to use it
Use a scatter when both axes are numbers and the question is the relationship: as one measure grows, what happens to the other. A line is the chart when x is ordered and you want the path between points. A bar is the chart when x is a category and you are comparing totals.
Do not use a scatter for parts of a whole. A pie or a donut is that chart. Do not invent a second y for bubble size. Size is its own channel.
Scatter and bubbles
There is no type: "bubble". A bubble chart is a scatter with encoding.size. Omit size and every point uses one radius, mark.pointSize when it is set. Set size and the radius follows that field.
Seats vs. renewal rate has no size channel. Yield by temperature sizes each point by plot. Spend vs usage sizes by customers. Sun hours and sugar sizes by grams.
Data
Each row is one point. encoding.x and encoding.y are quantitative fields. A string field name is enough. An object can set the title and the scale.
encoding.color splits the points into categories and gives the legend its entries. Spend vs usage colors by segment. Sun hours and sugar colors by variety. A scatter with no color field is one series.
Keep the size range inside the plot. Yield by temperature uses [5, 16]. A range of hundreds of pixels is clipped. a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest scatter. version, type, and a11y.alt are required. Four companies, revenue against employees. Size, color, and shape can be omitted. The points are circles of one radius.
{
"version": "1",
"type": "scatter",
"data": [
{
"revenue": 10,
"employees": 4
},
{
"revenue": 18,
"employees": 7
},
{
"revenue": 24,
"employees": 12
},
{
"revenue": 40,
"employees": 22
}
],
"encoding": {
"x": {
"field": "revenue",
"type": "quantitative"
},
"y": {
"field": "employees",
"type": "quantitative"
}
},
"a11y": {
"alt": "Companies with more employees also have more revenue."
}
}Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/qwik
import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";
export const Panel = component$(() => {
return <Chart spec={spec} />;
});npm install @chartkitdev/core
npm install @chartkitdev/angular
import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";
@Component({
standalone: true,
imports: [Chart],
template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
spec = spec;
}npm install @chartkitdev/core
npm install @chartkitdev/element
import "@chartkitdev/element";
const chart = document.querySelector("chart-kit");
chart.spec = spec;Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.
Examples
The rail switches among existing scatter specs. Seats vs. renewal rate is sixteen points and no size channel. Yield by temperature is seven bubbles. Spend vs usage is four bubbles on log scales. Sun hours and sugar is fifteen crates, colored by variety, and the tooltip names the fields.
Size
encoding.size is the bubble channel. It is an object with field and, usually, range, a pair of radii in pixels. Omit it and the points share one radius. That radius is mark.pointSize when the spec sets it.
{
"encoding": {
"size": { "field": "plot", "range": [5, 16] }
}
}Off removes the channel. On puts this example's size channel back, including its range. Seats vs. renewal rate has no third field, so On leaves the points at one radius.
Point shape
mark.pointShape is the marker. Omit it and the point is a circle. square and diamond are the other shapes a first scatter usually picks. Sun hours and sugar uses diamonds.
{
"mark": { "pointShape": "diamond" }
}triangle, cross, and none are in the schema. Set those in the playground. A size channel still wins over the shape: the field sets the radius, and the shape sets the outline.
Legend
A scatter with one series hides the legend. A color field with more than one category shows it. Omit legend, or set true, and the legend sits on top. false hides it. legend.position is top, right, bottom, left, or inside.
{
"legend": { "position": "bottom" }
}Tooltip
tooltip is on for a scatter when the key is omitted. Hovering a point shows the values. tooltip: false turns the card off. tooltip: true turns it on.
{
"tooltip": false
}{
"tooltip": true
}tooltip.fields chooses the rows in the card, and tooltip.position places it. Sun hours and sugar names variety, brix, and grams. Change those in the playground. Turning the card off and on again puts that object back.
The rest of the spec
encoding.x.scale.type and encoding.y.scale.type set a log scale when the values span orders of magnitude. Spend vs usage does that. mark.pointSize is the radius when size is omitted. mark.opacity fades overlapping points. Theme presets live on the playground, with the full option list.