Skip to main content

ScatterChart

ScatterChart

Visualize X/Y relationships with optional trend lines

Tags: chart correlation distribution analysis scientific

View Demo

The ScatterChart plots data points on X/Y coordinates to reveal relationships, clusters, and outliers. It's ideal for correlation analysis, scientific data, and identifying patterns. The optional trend line helps visualize the overall relationship between variables.

Reporting props marked Svelte only (valueFormat, showDataTable, exportable, reference lines, data zoom and so on) are available in @classic-homes/charts-svelte; React support is pending.

Import​

<script>
  import { ScatterChart } from '@classic-homes/charts-svelte';
</script>
// React
import { ScatterChart } from '@classic-homes/charts-react';

Basic Usage​

<script>
  import { ScatterChart } from '@classic-homes/charts-svelte';

  const data = {
    series: [
      {
        name: 'Dataset A',
        data: [
          [10.0, 8.04],
          [8.07, 6.95],
          [13.0, 7.58],
          [9.05, 8.81],
          [11.0, 8.33],
          [14.0, 7.66],
        ],
      },
      {
        name: 'Dataset B',
        data: [
          [8.0, 9.04],
          [6.07, 7.95],
          [11.0, 8.58],
          [7.05, 9.81],
          [9.0, 9.33],
          [12.0, 8.66],
        ],
      },
    ],
  };
</script>

<ScatterChart title="Data Correlation" {data} showTrendLine height={400} />

Props​

Chart-Specific Props​

Prop Type Default Description
data ScatterChartData required Chart data with coordinate pairs
showTrendLine boolean false Display a least-squares trend line per series, in the series colour; hidden with its series from the legend
symbolSize number | ((value: number[]) => number) 10 Point size (fixed or dynamic)
showLabels boolean false Show data labels
labelFormatter string | ((params: LabelFormatterParams) => string) - Data label template or function
xAxisConfig AxisConfig - Horizontal axis name, tick formatter, rotation and range
yAxisConfig AxisConfig - Vertical axis name, tick formatter, rotation and range
referenceLines ReferenceLine[] - Lines marking targets or statistics: { value: number | 'average' | 'median' | 'min' | 'max', label?, series?, style?, color? } (Svelte only)
referenceBands ReferenceBand[] - Shaded value ranges: { from, to, label?, color?, series? } (Svelte only)
legend ChartLegendConfig - Built-in legend position, alignment, icon and formatter
onLegendChange (visible: Record<string, boolean>) => void - Called when legend items are shown or hidden
renderLegend Snippet<[LegendRenderProps]> - Custom HTML legend (e.g. ChartLegend) instead of the built-in one; React takes a function returning a node
onClick (params: DataPointEventParams) => void - Callback when clicked
onHover (params: DataPointEventParams) => void - Callback when hovering over a point

Inherited Base Props​

Prop Type Default Description
title string required Chart title for accessibility
height number | string 400 Chart height
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
showLegend boolean true Show chart legend
showTooltip boolean true Show tooltip on hover
tooltipFormatter string | ((items: TooltipFormatterParams[]) => string) - Custom tooltip template or HTML function
tooltipValueFormatter (value: number) => string - Format values in the default tooltip
option EChartsOption - Raw ECharts option deep-merged over the generated one
description string - Optional description for screen readers
minHeight number - Minimum height in pixels; also bounds an 'auto' height
maxHeight number - Maximum height in pixels; also bounds an 'auto' height
loading boolean false Show loading skeleton; over existing data a loading overlay is shown instead (Svelte)
error string | null - Error message to display
onRetry () => void - Show a Retry button on the error state, calling this (Svelte only)
emptyMessage string - Message shown when data is empty
valueFormat ValueFormatPreset | Intl.NumberFormatOptions | ((value: number) => string) - How values are written in value axes, tooltips, labels and the data table: 'number', 'integer', 'compact', 'currency', 'currencyCents', 'percent', 'percentValue', 'days', Intl options or a function (Svelte only)
locale string 'en-US' Locale for valueFormat (Svelte only)
onReady (chart: EChartsType) => void - Called with the ECharts instance when it is created (Svelte only)
events Record<string, (params) => void> - Raw ECharts event handlers keyed by event name, e.g. datazoom (Svelte only)
showDataTable boolean | 'sr-only' 'sr-only' Render the data as a table: 'sr-only' for screen readers, true adds a visible "Show data" toggle, false for none (Svelte only)
exportable boolean | ChartExportConfig false Show PNG and CSV download buttons; or { image, csv, filename } (Svelte only)
patterns boolean false Fill series with decal patterns as well as colour, for colour-blind readers (Svelte only)
class string - Custom CSS class
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
showGrid boolean true Show grid lines (where applicable)

Data Structure​

interface ScatterChartData {
  series: Array<{
    name: string; // Series name for legend
    data: [number, number][]; // Array of [x, y] coordinate pairs
    color?: string; // Optional custom color
  }>;
}

Examples​

With Trend Line​

<ScatterChart title="Correlation Analysis" {data} showTrendLine height={400} />

Dynamic Point Size​

<ScatterChart title="Sized Points" {data} symbolSize={(value) => Math.sqrt(value[1]) * 3} />

Reference Lines (Svelte only)​

Reference lines and bands are drawn against the value (y) axis.

<ScatterChart
  title="Price vs Square Footage"
  {data}
  referenceLines={[{ value: 'median', label: 'Median price' }]}
  referenceBands={[{ from: 350000, to: 450000, label: 'Target band' }]}
/>

Accessibility​

  • Title provides aria-label for screen readers
  • Animations respect reduced motion preferences
  • Distinct colors for each series
On this page