# Scatter Chart

> A composable time-series scatter chart with offset rings, hover dimming, and animated enter

Source: https://ui.cortexcn.dev/docs/charts/scatter-chart

## Installation

```bash
npx shadcn@latest add @cortexcn/scatter-chart
```

## Usage

Build scatter charts by composing `ScatterChart` with one or more `Scatter` series, plus shared cartesian pieces (`Grid` or [`Background`](https://ui.cortexcn.dev/docs/utility/background), `XAxis`, `ChartTooltip`).

### Basic Example

```tsx
import {
  ScatterChart,
  Scatter,
  Grid,
  XAxis,
  ChartTooltip,
} from "@/components/charts";

const data = [
  { date: new Date("2025-01-01"), users: 1200 },
  { date: new Date("2025-02-01"), users: 1350 },
  { date: new Date("2025-03-01"), users: 1100 },
];

export default function SimpleScatter() {
  return (
    <ScatterChart data={data}>
      <Grid horizontal />
      <Scatter dataKey="users" />
      <XAxis />
      <ChartTooltip />
    </ScatterChart>
  );
}
```

### Multiple Series

Series colors default to the chart palette (`--chart-1` … `--chart-5`) in child order:

```tsx
<ScatterChart data={data}>
  <Grid horizontal />
  <Scatter dataKey="sessions" />
  <Scatter dataKey="conversions" />
  <XAxis />
  <ChartTooltip />
</ScatterChart>
```

### Offset Ring

Each dot is an inner fill plus an outer ring separated by a gap (`ringGap`):

```tsx
<Scatter dataKey="users" radius={6} strokeWidth={2} ringGap={2} />
```

### Hover Interaction

Non-active points can fade and blur while the crosshair is active:

```tsx
<Scatter
  dataKey="users"
  fadeOnHover
  inactiveOpacity={0.5}
  inactiveBlur={2}
  showActiveHighlight
/>
```

### Y Gradient

Color dots by vertical position with a chart-space gradient — lower values toward red, higher toward green. Set `strokeWidth={0}` for solid fills without rings:

```tsx
<Scatter dataKey="users" strokeWidth={0} yGradient />

// Custom stops
<Scatter
  dataKey="users"
  strokeWidth={0}
  yGradient={{ from: "var(--color-red-500)", to: "var(--color-emerald-500)" }}
/>
```

## Props

### ScatterChart

| Prop                | Type                        | Default            | Description                                                |
| ------------------- | --------------------------- | ------------------ | ---------------------------------------------------------- |
| `data`              | `Record<string, unknown>[]` | required           | Rows with a date (or `xDataKey`) and numeric series fields |
| `xDataKey`          | `string`                    | `"date"`           | Field used for the time x-axis                             |
| `margin`            | `Partial<Margin>`           | `40` all sides     | Chart margins                                              |
| `animationDuration` | `number`                    | `1100`             | Enter animation duration (ms)                              |
| `enterTransition`   | `Transition`                | line-chart default | Motion tween for enter                                     |
| `aspectRatio`       | `string`                    | `"2 / 1"`          | Container aspect ratio                                     |

### Scatter

| Prop                  | Type                                        | Default        | Description                                          |
| --------------------- | ------------------------------------------- | -------------- | ---------------------------------------------------- |
| `dataKey`             | `string`                                    | required       | Y value field                                        |
| `yAxisId`             | `string \| number`                          | `"left"`       | Y-scale group for biaxial charts (pair with `YAxis`) |
| `fill`                | `string`                                    | series palette | Inner dot fill                                       |
| `stroke`              | `string`                                    | same as `fill` | Outer ring color                                     |
| `strokeWidth`         | `number`                                    | `2`            | Outer ring width (0 disables)                        |
| `ringGap`             | `number`                                    | `2`            | Gap between fill and ring (px)                       |
| `radius`              | `number`                                    | `5`            | Inner dot radius (px)                                |
| `fadeOnHover`         | `boolean`                                   | `true`         | Dim/blur non-active points on hover                  |
| `inactiveOpacity`     | `number`                                    | `0.5`          | Opacity for dimmed points                            |
| `inactiveBlur`        | `number`                                    | `2`            | Blur (px) for dimmed points                          |
| `showActiveHighlight` | `boolean`                                   | `true`         | Scale up the active point                            |
| `yGradient`           | `boolean \| { from?: string; to?: string }` | —              | Color dots by y-position (default red → green)       |

## Shared Components

Use the same cartesian building blocks as `LineChart`:

- `Grid` — horizontal/vertical grid lines
- [`Background`](https://ui.cortexcn.dev/docs/utility/background) — pattern fill when grid lines are hidden (see [gallery](https://ui.cortexcn.dev/charts/scatter-chart))
- `YAxis` — value labels (single shared scale; see [Y Axis](https://ui.cortexcn.dev/docs/utility/axis/y-axis))
- `XAxis` — date labels with crosshair fade
- `ChartTooltip` — crosshair, date pill, and series rows