# Scatter chart

Plot two measures against each other, one point per dimension value.

- Component: `<ScatterChart />`, imported from `em-kit`
- Required props: `pointDimension`, `xMeasure`, `yMeasure` and `results`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/scatter-chart
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/scatter-chart/playground

`ScatterChart` takes `pointDimension` + `xMeasure` + `yMeasure`. Its siblings name their fields differently: `BubbleChart` takes `pointDimension` + `xMeasure` + `yMeasure` + `bubbleSizeMeasure`.

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A chart fills its parent, so the parent needs a height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## Usage

```tsx
import {
  ChartsProvider,
  ScatterChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const account = dimension({ name: 'account', title: 'Account' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const seats = measure({ name: 'seats', title: 'Seats' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <ScatterChart
        title="Revenue vs seats"
        pointDimension={account}
        groupByDimension={plan}
        xMeasure={seats}
        yMeasure={revenue}
        results={results(rows)}
        showValueLabels={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { account: 'Alder', plan: 'Starter', seats: 40, revenue: 44000 },
  { account: 'Birch', plan: 'Starter', seats: 66, revenue: 60000 },
  { account: 'Cedar', plan: 'Starter', seats: 92, revenue: 49000 },
  { account: 'Dune', plan: 'Growth', seats: 118, revenue: 78000 },
  { account: 'Ember', plan: 'Growth', seats: 144, revenue: 64000 },
  { account: 'Fjord', plan: 'Growth', seats: 170, revenue: 96000 },
  { account: 'Grove', plan: 'Growth', seats: 196, revenue: 84000 },
  { account: 'Harbor', plan: 'Enterprise', seats: 226, revenue: 131000 },
  { account: 'Isle', plan: 'Enterprise', seats: 258, revenue: 114000 },
  { account: 'Juniper', plan: 'Enterprise', seats: 296, revenue: 176000 },
  { account: 'Kite', plan: 'Enterprise', seats: 334, revenue: 152000 },
];
```

- Each row is one point. `groupByDimension` colours the points and adds the legend.

## States

The chart draws its own states from `results`: a skeleton while `isLoading` is true and it has no rows, a spinner in the header while it reloads rows it already has, an empty state when `data` is `[]`, and the message when `error` is set. Pass your query’s state straight through.

## Examples

### Point labels

Each point labelled with its dimension value, so outliers name themselves. A label sits under its point, so both axes start at zero here to keep the labels clear of them.

```tsx
import {
  ChartsProvider,
  ScatterChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const account = dimension({ name: 'account', title: 'Account' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const seats = measure({ name: 'seats', title: 'Seats' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <ScatterChart
        title="Revenue vs seats"
        pointDimension={account}
        groupByDimension={plan}
        xMeasure={seats}
        yMeasure={revenue}
        results={results(rows)}
        showValueLabels={false}
        showPointLabels
        xAxisRangeMin={0}
        yAxisRangeMin={0}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { account: 'Alder', plan: 'Starter', seats: 40, revenue: 44000 },
  { account: 'Birch', plan: 'Starter', seats: 66, revenue: 60000 },
  { account: 'Cedar', plan: 'Starter', seats: 92, revenue: 49000 },
  { account: 'Dune', plan: 'Growth', seats: 118, revenue: 78000 },
  { account: 'Ember', plan: 'Growth', seats: 144, revenue: 64000 },
  { account: 'Fjord', plan: 'Growth', seats: 170, revenue: 96000 },
  { account: 'Grove', plan: 'Growth', seats: 196, revenue: 84000 },
  { account: 'Harbor', plan: 'Enterprise', seats: 226, revenue: 131000 },
  { account: 'Isle', plan: 'Enterprise', seats: 258, revenue: 114000 },
  { account: 'Juniper', plan: 'Enterprise', seats: 296, revenue: 176000 },
  { account: 'Kite', plan: 'Enterprise', seats: 334, revenue: 152000 },
];
```

### One colour

Every point in one colour with no grouping, for a plain correlation plot.

```tsx
import {
  ChartsProvider,
  ScatterChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const account = dimension({ name: 'account', title: 'Account' });
const seats = measure({ name: 'seats', title: 'Seats' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <ScatterChart
        title="Revenue vs seats"
        pointDimension={account}
        xMeasure={seats}
        yMeasure={revenue}
        results={results(rows)}
        showLegend={false}
        showValueLabels={false}
        pointColor="#0ea5e9"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { account: 'Alder', seats: 40, revenue: 44000 },
  { account: 'Birch', seats: 66, revenue: 60000 },
  { account: 'Cedar', seats: 92, revenue: 49000 },
  { account: 'Dune', seats: 118, revenue: 78000 },
  { account: 'Ember', seats: 144, revenue: 64000 },
  { account: 'Fjord', seats: 170, revenue: 96000 },
  { account: 'Grove', seats: 196, revenue: 84000 },
  { account: 'Harbor', seats: 226, revenue: 131000 },
  { account: 'Isle', seats: 258, revenue: 114000 },
  { account: 'Juniper', seats: 296, revenue: 176000 },
  { account: 'Kite', seats: 334, revenue: 152000 },
];
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `pointDimension` | `Dimension` | yes |  | The dimension that names each point, used in the tooltip and the point label. |
| `xMeasure` | `Measure` | yes |  | The measure plotted along the x-axis. |
| `yMeasure` | `Measure` | yes |  | The measure plotted along the y-axis. |
| `results` | `DataResponse` | yes |  | Your query’s state: `{ isLoading, data, error }`, where `data` is your rows. `results(rows)` builds it from an array. |
| `groupByDimension` | `Dimension` | no |  | An optional dimension that colours the points by group. |
| `pointColor` | `string` | no |  | One colour for every point, in place of the theme’s. |
| `showLegend` | `boolean` | no | `true` | Show the legend. A chart with one series shows none; entries wrap onto more lines when they do not fit. |
| `showTooltips` | `boolean` | no | `true` | Show a formatted tooltip on hover. |
| `showPointLabels` | `boolean` | no | `false` | Label each point with its `pointDimension` value. |
| `showValueLabels` | `boolean` | no | `true` | Print each value on the chart. |
| `showLogarithmicScale` | `boolean` | no | `false` | Use a logarithmic value axis, for values that span several orders of magnitude. |
| `xAxisLabel` | `string` | no |  | A title under the x-axis. |
| `yAxisLabel` | `string` | no |  | A title beside the y-axis. |
| `xAxisRangeMin` | `number` | no |  | Fix the lowest value on the x-axis. When unset, a horizontal bar chart’s axis includes zero, and a scatter or bubble chart’s fits the data. |
| `xAxisRangeMax` | `number` | no |  | Fix the highest value on the x-axis. When unset, it fits the data. |
| `yAxisRangeMin` | `number` | no |  | Fix the lowest value on the y-axis. When unset, a bar, line or area chart’s axis includes zero, and a scatter or bubble chart’s fits the data. |
| `yAxisRangeMax` | `number` | no |  | Fix the highest value on the y-axis. When unset, it fits the data. |
| `reverseXAxis` | `boolean` | no | `false` | Reverse the order of the x-axis. |
| `onPointClick` | `(payload: ScatterChartOptionsClickArg) => void` | no |  | Called with the clicked point’s dimension value and its x and y values. |
| `componentName` | `string` | no |  | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. |
| `trackingId` | `string` | no |  | An id included in the same events, to tell two instances apart. |
| `title` | `string` | no |  | The card’s title. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |
| `hideMenu` | `boolean` | no | `false` | Hide the card’s header: the title, description and menu. |
| `menuOptions` | `("csv" \| "xlsx" \| "png" \| "maximize")[]` | no | `["csv", "xlsx", "png", "maximize"]` | Which entries the card menu offers. Pass `[]` for none. |

```ts
type ScatterChartOptionsClickArg = { xMeasureValue: string; yMeasureValue: string; pointDimensionValue: string | undefined; groupByDimensionValue: string | null | undefined; pointDimensionTimeRange: TimeRange; groupByDimensionTimeRange: TimeRange; }
type TimeRange = { from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefined
```

Each is exported from `em-kit` as a type, for example `import type { ScatterChartOptionsClickArg } from 'em-kit'`.

A click payload’s `TimeRange` is `undefined` unless the clicked field is a time dimension, and its `relativeTimeString` is always `undefined`, so read it as `range?.from`. When you pass one, `from` and `to` are enough.

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. [Field options](/docs/describing-your-data.md#field-options) describes them.
