ScatterChart
Scatter plots of two numeric fields, one point per row, split into colored series by a field.
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/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per point. |
xKey, yKey | numeric fields of T | required | Horizontal and vertical coordinates. |
ariaLabel | string | required | Accessible chart name. |
seriesKey | string or number field of T | one series | Field splitting rows into colored series. |
series | { value?, label?, color? }[] | - | Labels, colors, and order. value is required with seriesKey. |
idKey | string or number field of T | row index | Unique, stable point identity; duplicates throw. |
xLabel, yLabel | string | field names | Axis names in the tooltip. |
formatX, formatY | (value: number) => string | grouped number | Tick and tooltip formatting; include units here. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Plot height and point size (SCATTER_CHART_LAYOUT). |
legend | boolean | { align?, placement? } | shown for 2+ series | Series legend; items toggle their series. |
tooltip | boolean | true | Hover and keyboard tooltip. |
grid | boolean | "horizontal" | "vertical" | true | Reference lines in both, one, or no direction. |
xDomain, yDomain | [number, number] | fitted, includes zero | Fixed axis extents. |
xTicks, yTicks | number[] | rounded, spaced to the plot | Exact axis ticks. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid points exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
createScatterChartDefinition(options) | function | - | Same options plus hiddenSeries; returns an extensible TanStack definition. |
ScatterChartSeries, ScatterChartOptions, ScatterChartDatum, ScatterChartDefinition | types | - | 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/yLabeland include units informatX/formatYso the tooltip reads on its own.