Scatter Chart

Plots points to show how two numbers relate to each other.

10°C15°C20°C25°C28.1°C0200400600800

Usage

Code
import { ScatterChart } from '@leverui/components';
Code
<ScatterChart
  data={[
    { temperature: 14.2, sales: 215 },
    { temperature: 16.4, sales: 325 },
  ]}
  xKey="temperature"
  yKey="sales"
  series={[{ name: 'sales', color: 'teal.solid' }]}
  xDomain={[10, 28.1]}
  yDomain={[0, 800]}
  aria-label="Sales by temperature"
/>

Examples

Legend

Label the blue coordinate group beneath its scatter plot.

045901351800100200300400
Group 1

Multiple

Separate two labeled clusters and enable point tooltips.

901301702102500100200300400

Connect Dots

Connect the six source-ordered teal points with gray segments.

045901351800100200300400

Trend Line

Add the least-squares red line to the temperature scatter plot.

1015202528.10200400600800

Props

Data

PropDefaultTypeDescription
data—readonly ScatterDatum[]Rows to plot. Required.
xKey—stringField that holds the X-axis number. Required.
yKey—stringField that holds the Y-axis number. Required.
series—readonly ScatterSeries[]Groups of points and their colors. Required.

Rows where either value is not a number are skipped.

Points and lines

PropDefaultTypeDescription
connectDotsfalsebooleanJoin each series' points, in data order.
trendLinefalsebooleanDraw one best-fit line through all points.

trendLine needs at least two points with different X values.

Axes

PropDefaultTypeDescription
xDomain—readonly [number, number]Lowest and highest number on the X-axis.
yDomain—readonly [number, number]Lowest and highest number on the Y-axis.
xTicks—readonly number[]Exact numbers that get an X-axis label.
xFormatter—(value: number) => stringFormat each X-axis label.

Without xDomain, the X-axis runs from the lowest to the highest X value in the data. Without yDomain, the Y-axis runs from zero to a round number at or above the highest Y value. A domain whose first number is not lower than its second throws an error.

Without xTicks, the X-axis gets five evenly spaced labels. The Y-axis always has five.

Legend and tooltip

PropDefaultTypeDescription
showLegendfalsebooleanShow a legend below the plot.
tooltipfalsebooleanShow both values of the point under the pointer.

The tooltip also draws dashed guide lines at the point. The legend lists the series from last to first.

Size

PropDefaultTypeDescription
height384numberHeight, in pixels.
topInset5numberSpace above the plot, in pixels.
leftInset65numberSpace left of the plot, in pixels. Holds the Y-axis labels.
rightInset6numberSpace right of the plot, in pixels.

A negative inset, or insets that leave no room for the plot, throw an error. The space below the plot is fixed at 35 pixels, or 64 with a legend, so height must be greater than that plus topInset.

Other attributes and event handlers go to the root element.

Series options

FieldTypeDescription
namestringName in the legend and tooltip. Required.
colorstringColor token such as teal.solid, or a CSS color. Required.
groupIdstringDraw only the rows whose id field matches.

Without groupId, a series draws every row.

Code
<ScatterChart
  data={[
    { id: 'group1', x: 100, y: 200 },
    { id: 'group2', x: 140, y: 250 },
  ]}
  xKey="x"
  yKey="y"
  series={[
    { name: 'Group 1', color: 'blue.solid', groupId: 'group1' },
    { name: 'Group 2', color: 'green.solid', groupId: 'group2' },
  ]}
/>

Keyboard

The chart takes focus when the tooltip is on. Focus shows the first point.

KeyAction
ArrowLeft ArrowRightPrevious or next point.
EscapeClose the tooltip.

Styling

Code
<ScatterChart class="sales-scatter" data={data} xKey="x" yKey="y" series={series} />
Code
.sales-scatter {
  --leverui-scatter-chart-trend-stroke: #2f6f62;
  --leverui-scatter-chart-legend-gap: 1rem;
}

.sales-scatter .leverui-scatter-chart__point {
  opacity: 0.8;
}

Variables

VariableDefaultDescription
--leverui-scatter-chart-width100%Width of the chart's box.
--leverui-scatter-chart-heightThe height propHeight of the chart's box.
--leverui-scatter-chart-axis-strokeBorder colorAxis line and tick mark color.
--leverui-scatter-chart-axis-stroke-width1pxAxis line and tick mark thickness.
--leverui-scatter-chart-tick-colorMuted text colorAxis label color.
--leverui-scatter-chart-tick-font-size12pxAxis label size.
--leverui-scatter-chart-cursor-strokeBorder colorGuide line color at the active point.
--leverui-scatter-chart-cursor-dasharray3 3Guide line dash pattern.
--leverui-scatter-chart-trend-strokeSolid redTrend line color.
--leverui-scatter-chart-trend-stroke-width2pxTrend line thickness.
--leverui-scatter-chart-connection-strokeBorder colorColor of the line joining the points.
--leverui-scatter-chart-connection-stroke-width2pxThickness of that line.
--leverui-scatter-chart-legend-bottom8pxGap between the legend and the bottom edge.
--leverui-scatter-chart-legend-gap12pxSpace between legend items.
--leverui-scatter-chart-legend-font-size12pxLegend text size.
--leverui-scatter-chart-legend-colorMuted text colorLegend text color.
--leverui-scatter-chart-legend-swatch-size8pxWidth and height of a legend swatch.
--leverui-scatter-chart-legend-swatch-radius2pxSwatch corner radius.
--leverui-scatter-chart-legend-swatch-gap4pxSpace between a swatch and its name.

Classes

Root: .leverui-scatter-chart.

Parts, each prefixed with .leverui-scatter-chart__: svg, axes, axis-line, tick, tick-label, cursor, trend, series, connection, point, legend, legend-item, legend-swatch.

Each series group has a data-scatter-series attribute set to the series name. Tooltip: .leverui-chart-tooltip.