PlScatterChart

Two numbers per point, and whether they move together. Both axes measure, which makes this the only chart in the library with no categories.

React

import { PlScatterChart } from 'plass-ui';

<PlScatterChart series={stores} />;

import 'package:plass_ui/plass_ui.dart';

PlScatterChart(series: stores);

There is no column a mark belongs to and no order the points could be shuffled out of. A point with a z is drawn as a bubble and one without it as a dot, so a scatter and a bubble chart are the same component reading the same data. The third number is simply present or not.

Props

Prop	Type	Default	Description
series *	readonly PlassChartSeries[]	—	The data. Every point needs a number or a date for its x
categories	readonly PlassChartCategory[]	—	What the points sit against, when they do not carry their own x
shape	'auto' | 'varied' | 'circle' | 'square' | 'triangle' | 'diamond' | 'cross'	'auto'	What each mark is drawn as. auto splits by shape from the fourth series on, because colour separates three
pointRadius	number	—	The radius of a mark with no z. Defaults to the size ladder
maxRadius	number	—	The largest bubble's radius, and the room reserved around the plot. Defaults to a twelfth of the height
xAxis	PlassChartAxis	—	The x axis, which measures here rather than naming
yAxis	PlassChartAxis	—	The value axis
legend	PlassChartLegend	—	The legend
tooltip	PlassChartTooltip	—	The tooltip
height	number | string	—	How tall the plot is
format	Intl.NumberFormatOptions	—	How a value is written
label	string	'Chart'	What the whole drawing is called
empty	ReactNode	—	What is drawn when there is nothing to draw
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Type scale, plot height and the default mark radius

Prop	Type	Default	Description
series *	List<PlassChartSeries>	—	The data. Every point needs a number or a date for its x
categories	List<PlassChartCategory>?	—	What the points sit against, when they do not carry their own x
shape	PlScatterShape	PlScatterShape.auto	What each mark is drawn as. A seven-member enum where React takes MarkShape | 'varied' | 'auto'
pointRadius	double?	—	The radius of a mark with no z. Defaults to the size ladder
maxRadius	double?	—	The largest bubble's radius, and the room reserved around the plot. Defaults to a twelfth of the height
xAxis	PlChartAxis	PlChartAxis()	The x axis, which measures here rather than naming
yAxis	PlChartAxis	PlChartAxis()	The value axis
legend	PlChartLegend	PlChartLegend()	The legend
tooltip	PlChartTooltip	PlChartTooltip()	The tooltip
height	double?	—	How tall the plot is
format	String Function(double)?	—	How a value is written
semanticLabel	String?	'Chart'	What the whole drawing is called
empty	Widget?	—	What is drawn when there is nothing to draw
sizeshared	PlassSize	PlassSize.md	Type scale, plot height and the default mark radius

Each point's x must be a number or a date. Text has no place on a number line, and a chart of named things against one measure is a bar chart.

Neither axis is forced to zero. What a position encodes is a place, so cropping a scale slides every mark by the same amount and the shape of the cloud survives, which is not true of a bar, whose length is its value.

What the shared axes mean across the library is in prop conventions.

Examples

Bubbles

React

import { PlScatterChart } from 'plass-ui';

const markets = [
  {
    name: 'Europe',
    data: [
      { x: 8.2, y: 62, z: 84 },
      { x: 11.4, y: 71, z: 47 },
      { x: 6.9, y: 55, z: 120 }
    ]
  },
  {
    name: 'Asia',
    data: [
      { x: 14.1, y: 48, z: 260 },
      { x: 9.6, y: 66, z: 31 },
      { x: 12.8, y: 59, z: 175 }
    ]
  }
];

export default function ScatterChartBubbles() {
  return (
    <PlScatterChart
      className="w-full"
      series={markets}
      label="Growth against margin"
      xAxis={{ label: 'Growth (%)' }}
      yAxis={{ label: 'Margin (%)' }}
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

PlassChartDatum _at(double x, double y, double z) =>
    PlassChartDatum.point(PlassChartPoint(x: PlassChartCategory.number(x), y: y, z: z));

final List<PlassChartSeries> _markets = <PlassChartSeries>[
  PlassChartSeries(
    name: 'Europe',
    data: <PlassChartDatum>[_at(8.2, 62, 84), _at(11.4, 71, 47), _at(6.9, 55, 120)],
  ),
  PlassChartSeries(
    name: 'Asia',
    data: <PlassChartDatum>[_at(14.1, 48, 260), _at(9.6, 66, 31), _at(12.8, 59, 175)],
  ),
];

class ScatterChartBubbles extends StatelessWidget {
  const ScatterChartBubbles({super.key});

  @override
  Widget build(BuildContext context) {
    return PlScatterChart(
      series: _markets,
      semanticLabel: 'Growth against margin',
      xAxis: const PlChartAxis(label: 'Growth (%)'),
      yAxis: const PlChartAxis(label: 'Margin (%)'),
    );
  }
}

A point's z is an area, not a radius. Encoded as a radius, a value twice as large would draw a mark four times the size; the square root keeps the ink on the page proportional to the number behind it. One scale covers the whole chart and is taken over every series including the hidden ones, so two bubbles the same size mean the same number wherever they are, and switching a series off does not resize the rest.

Bubbles are painted largest first. A small bubble inside a big one is invisible if the big one is drawn on top of it, and the usual fix (half alpha on every fill) would undo the contrast the palette was solved for.

shape

React

import { PlScatterChart } from 'plass-ui';

const runs = [1, 2, 3, 4, 5].map((n) => ({
  name: `Run ${n}`,
  data: [
    { x: n * 4, y: 20 + n * 6 },
    { x: n * 4 + 9, y: 34 + n * 4 },
    { x: n * 4 + 17, y: 26 + n * 7 }
  ]
}));

export default function ScatterChartShape() {
  return <PlScatterChart className="w-full" series={runs} label="Five runs" shape="varied" />;
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

PlassChartDatum _at(double x, double y) =>
    PlassChartDatum.point(PlassChartPoint(x: PlassChartCategory.number(x), y: y));

final List<PlassChartSeries> _runs = <PlassChartSeries>[
  for (int n = 1; n <= 5; n += 1)
    PlassChartSeries(
      name: 'Run $n',
      data: <PlassChartDatum>[
        _at(n * 4, 20 + n * 6),
        _at(n * 4 + 9, 34 + n * 4),
        _at(n * 4 + 17, 26 + n * 7),
      ],
    ),
];

class ScatterChartShape extends StatelessWidget {
  const ScatterChartShape({super.key});

  @override
  Widget build(BuildContext context) {
    return PlScatterChart(series: _runs, semanticLabel: 'Five runs', shape: PlScatterShape.varied);
  }
}

auto, the default, draws circles while colour alone can carry identity, and switches to a shape per series from the fourth on. That threshold is measured rather than chosen: taking the first three palette slots, the closest pair under deuteranopia is ΔE 64 on the light sheet and 51 on the dark one; add the fourth and those fall to 4.9 and 2.8. Past three, colour is not telling anyone anything, and a shape is the one channel a dot has going spare.

A series that carries a color of its own does not count against that ceiling. The caller has already answered the question it exists to ask.

varied turns the shapes on regardless, which is what to use when the chart will be printed or read in greyscale. Naming one of the five shapes puts every mark in it, and on four or more series that is opting out of the second channel.

pointRadius and maxRadius

pointRadius is the radius of a mark with no z. maxRadius is how big the largest bubble may get, and it doubles as the room reserved around the plot. A mark is drawn from its centre, so a bubble at the largest x would otherwise hang over the edge.

Accessibility

• The drawing carries the chart's name, and every point is handed over as text: each series, then its points as x, y pairs with the z in brackets where there is one.
• On React the picture is a role="img" and a tab stop, and the arrow keys walk the marks in the order the data was given, not the order they are painted in, which is largest-first and would be an order the reader cannot anticipate.
• On React the same numbers are written into a table under the chart: a row per point rather than the grid every other chart uses, because two points that are both the fifth of their series have nothing to do with each other and a shared row would invent a relationship. Its columns are named from the axis labels, falling back to x, y and z.
• Past three series the marks differ in shape as well as in hue, and the legend's swatches show the shapes.