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.

spec.json
{
  "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.

Import@chartkitdev/core/charts/scatterBundle@chartkitdev/core/allFamilyCore
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
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} />;
});
Angular
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;
}
Custom element
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
{
  "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
{
  "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
{
  "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": false
}
tooltip true
{
  "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.