ScatterChart

Scatter plots of two numeric fields, one point per row, split into colored series by a field.

stable

Quick Preview

Price vs. size

Lekki listings · sqm by ₦m

Usage

import { ScatterChart } from "@giddaa-housing/ui/scatter-chart";

<ScatterChart
  data={listings}
  xKey="size"
  yKey="price"
  seriesKey="area"
  series={[
    { value: "Lekki", label: "Lekki" },
    { value: "Yaba", label: "Yaba", color: "var(--color-chart-3)" },
  ]}
  xLabel="Size"
  yLabel="Price"
  formatX={(value) => `${value} sqm`}
  formatY={(value) => `₦${value}m`}
  ariaLabel="Listing price against size by area"
/>

A scatter plot has no shared category row: each row is one point, and both axes are numeric. Rows missing either coordinate are omitted, never plotted at zero. Rows stay in one array; seriesKey splits them into series, and series sets their labels, colors, and order (each entry's value matches a seriesKey value). The tooltip lists both coordinates under the series name, labeled with xLabel and yLabel and formatted with formatX and formatY.

Examples

Single series

Without seriesKey, every row belongs to one series; series={[{ label }]} names it.

Price vs. size

Lekki listings · sqm by ₦m

Multiple series

Neighbourhood price vs. size

Active listings · sqm by ₦m

Pinned domain, horizontal grid, custom color

xDomain and yDomain fix the extents, grid="horizontal" keeps one set of reference lines, and series[].color restyles a series.

Score vs. rental yield

Pinned domains · custom colour

Props

Prop/APITypeDefaultDescription
datareadonly T[]requiredOne row per point.
xKey, yKeynumeric fields of TrequiredHorizontal and vertical coordinates.
ariaLabelstringrequiredAccessible chart name.
seriesKeystring or number field of Tone seriesField splitting rows into colored series.
series{ value?, label?, color? }[]-Labels, colors, and order. value is required with seriesKey.
idKeystring or number field of Trow indexUnique, stable point identity; duplicates throw.
xLabel, yLabelstringfield namesAxis names in the tooltip.
formatX, formatY(value: number) => stringgrouped numberTick and tooltip formatting; include units here.
size"sm" | "md" | "lg"inherited, otherwise "md"Plot height and point size (SCATTER_CHART_LAYOUT).
legendboolean | { align?, placement? }shown for 2+ seriesSeries legend; items toggle their series.
tooltipbooleantrueHover and keyboard tooltip.
gridboolean | "horizontal" | "vertical"trueReference lines in both, one, or no direction.
xDomain, yDomain[number, number]fitted, includes zeroFixed axis extents.
xTicks, yTicksnumber[]rounded, spaced to the plotExact axis ticks.
emptyMessageReactNode"No data to display"Shown when no valid points exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
createScatterChartDefinition(options)function-Same options plus hiddenSeries; returns an extensible TanStack definition.
ScatterChartSeries, ScatterChartOptions, ScatterChartDatum, ScatterChartDefinitiontypes-Exported for typed series and builders.

Accessibility

  • Provide a meaningful ariaLabel; focus the chart and use arrow keys to move between points.
  • Keep the legend whenever more than one series renders; a single series is named by the card title.
  • Name both axes with xLabel/yLabel and include units in formatX/formatY so the tooltip reads on its own.

On this page