Density chart

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Usage

Rows are observations, as in a scatter plot: a number under xDataKey and one under yDataKey. Add groupDataKey to estimate each group on its own.

import {
  DensityChart,
  DensityContours,
  DensityPoints,
  DensityTooltip,
  DensityXAxis,
  DensityYAxis,
} from "@/components/ui/charts";

const bookings = [
  { days: 4, fare: 540 },
  { days: 12, fare: 470 },
  { days: 38, fare: 360 },
  { days: 55, fare: 320 },
  { days: 61, fare: 300 },
  { days: 90, fare: 260 },
];

export const BookingsChart = () => (
  <DensityChart
    ariaLabel="Fares by days booked ahead"
    data={bookings}
    xDataKey="days"
    yDataKey="fare"
  >
    <DensityContours />
    <DensityPoints />
    <DensityXAxis label="Days booked ahead" />
    <DensityYAxis />
    <DensityTooltip xLabel="Booked ahead" yLabel="Fare" />
  </DensityChart>
);

Anatomy

The bands always sit under the points, whatever order you write them in. Only the points react to the pointer, so a chart without DensityPoints has no tooltip.

<DensityChart data={data} xDataKey="days" yDataKey="fare">
  <DensityGrid />
  <DensityContours />
  <DensityPoints />
  <DensityXAxis label="Days booked ahead" />
  <DensityYAxis />
  <DensityTooltip />
</DensityChart>

• DensityChart: Holds the observations, the scales and, with groupDataKey, the groups.
• DensityGrid: Dashed guide lines behind the bands.
• DensityContours: The estimate as nested filled bands, 8 levels by default.
• DensityPoints: The observations as dots. Hover, the tooltip and keyboard focus land on these.
• DensityXAxis: Tick labels along the bottom, with an optional label.
• DensityYAxis: Tick labels on the left, with an optional label.
• DensityTooltip: The hovered point's x and y, titled with its group.
• DensityLegend: Each group and its color. It needs groupDataKey.

Smoothing and levels

bandwidth on <DensityContours> is the smoothing radius in pixels, 20 by default. Raise it for broad, soft shapes, or lower it to keep nearby clusters apart. Because it's in pixels, the same data looks smoother on a small chart.

thresholds is the number of levels (8), or an array of exact density values when two charts must draw the same levels.

Groups

Set groupDataKey and each group gets its own estimate, colored --chart-1, --chart-2 and so on in order of appearance. groupColors maps group names to colors of your own.

<DensityLegend /> lists the groups under the plot, and the tooltip uses the hovered point's group as its title.

Contours on their own

Leave out <DensityPoints> and the axes to show only where things land, like taps on a screen. More levels with a lower fillOpacity give finer bands.

Without points there's nothing to hover or focus, so add an ariaDescription that says what the shape shows.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

className goes on the chart's container, so size and spacing are utility classes.

The bands' look is on <DensityContours>: fillOpacity for each band (0.14, so stacked levels darken toward a peak), strokeWidth and strokeOpacity for the outlines, and color for one color across every group.

content on <DensityTooltip> gets the hovered row as point and its index in data, so the panel can show fields that aren't on either axis.

<DensityTooltip
  content={({ point }) => (
    <div className="px-3 py-2 text-sm">
      {String(point.route)}, booked {Number(point.days)} days ahead
    </div>
  )}
/>

Where a part renders content of its own, you pass it in. In React:

• DensityTooltip: content={({ point, index }) => …}

Loading state

With status="loading", two clusters of skeleton bands breathe in the plot, with skeleton dots when the chart has <DensityPoints>. The axes and grid stay, and the pointer is ignored.

Switch to "ready" and the real bands rise level by level. loadingLabel puts a short line of text over the skeleton.

Animation

The bands rise one level at a time, outermost first, spread over animationDuration (900 ms). The points follow 200 ms later in a wave from left to right.

Change revealSignature to play it again. animate={false} and reduced motion both show the chart at rest.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

Groups take --chart-1 to --chart-5 in order of appearance, and a chart without groups draws in --chart-1. Past five groups the colors repeat, so pass groupColors for the rest.

:root {
  --chart-grid: var(--muted);
  --chart-label: var(--foreground);
}

Accessibility

The chart is announced as an image named by ariaLabel ("Density chart" by default). Describe the clusters in ariaDescription, since the bands themselves can't be read out.

Keyboard focus moves through the points, not the bands, so keep <DensityPoints> when people need to reach the values.

API reference

DensityChart

DensityContours

DensityPoints

DensityGrid

DensityXAxis

DensityYAxis

DensityTooltip

DensityLegend