Hexbin 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

Each row is one observation, with a number under xDataKey and one under yDataKey. Rows missing either are skipped.

<script setup lang="ts">
import {
  HexbinCells,
  HexbinChart,
  HexbinTooltip,
  HexbinXAxis,
  HexbinYAxis,
} from "@/components/ui/charts";

const sessions = [
  { minutes: 1.4, pages: 2 },
  { minutes: 2.2, pages: 3 },
  { minutes: 2.6, pages: 2 },
  { minutes: 6.8, pages: 7 },
  { minutes: 9.1, pages: 6 },
];
</script>

<template>
  <HexbinChart
    ariaLabel="Session length and pages viewed"
    :data="sessions"
    x-data-key="minutes"
    y-data-key="pages"
  >
    <HexbinCells />
    <HexbinXAxis />
    <HexbinYAxis />
    <HexbinTooltip value-label="Sessions" />
  </HexbinChart>
</template>

Anatomy

The cells always draw over the grid, whatever order you write the children in. Leave out the axes, tooltip or legend and they aren't drawn.

<HexbinChart :data="data" x-data-key="minutes" y-data-key="pages">
  <HexbinGrid />
  <HexbinCells />
  <HexbinXAxis />
  <HexbinYAxis />
  <HexbinTooltip value-label="Sessions" />
  <HexbinLegend title="Sessions" />
</HexbinChart>

• HexbinChart: Holds the observations and sets up the x and y scales.
• HexbinGrid: Dashed guide lines, horizontal unless you add vertical.
• HexbinCells: The hexagons. binWidth sets their size, valueDataKey and reduce what their color shows.
• HexbinXAxis: Tick labels along the bottom.
• HexbinYAxis: Tick labels on the left.
• HexbinTooltip: The hovered bin's position and value.
• HexbinLegend: One swatch per color step and the range it covers, under the plot.

Bin size

binWidth on <HexbinCells> is the distance between neighboring hexagon centers, 22 px by default. Points are binned in pixels after the chart is sized, so a narrow chart puts more of them in each bin.

That keeps the hexagons a readable size on a phone. If you need the same bins at every width, aggregate the data yourself and use a heatmap.

Sums and averages

By default a bin's color is its count. Point valueDataKey at a field and each bin sums it, or averages it with reduce="mean". The tooltip then shows the value and the count.

Format the value with formatValue on both <HexbinTooltip> and <HexbinLegend> so they agree.

Tooltip content

The default panel is titled with the bin's center, in the axes' formats, and lists its value. valueLabel renames that row and formatPosition rewrites the title.

For anything else, pass content. It gets the hovered bin with its x, y, count, value and the rows that fell in it, and renders inside the same panel.

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.

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

Fills come in steps, four by default, from --chart-scale-02 to --chart-scale-05. The cut points sit on a square-root scale, so a few crowded bins don't push the rest into the lightest step.

To choose them yourself, pass colors and thresholds (one fewer). gap sets the space between hexagons and stroke gives them an outline. The legend reads whatever you pass.

<HexbinCells
  :colors="[
    'var(--chart-scale-02)',
    'var(--chart-scale-04)',
    'var(--chart-scale-05)',
  ]"
  :gap="0"
  :thresholds="[5, 20]"
/>

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

• HexbinTooltip: <template #content="{ bin, index }">

Loading state

Pass status="loading" and a patch of skeleton hexagons shimmers in the plot, while the axes and grid stay put. The pointer is ignored until you switch to "ready", then the real bins sweep in.

There's no separate placeholder. With no rows yet, pass an empty data array along with xDomain and yDomain, so the axes don't change when the data lands.

Animation

The hexagons grow in as a wave from left to right. The wave takes animationDuration (900 ms) to cross the plot and each hexagon 450 ms to settle.

New data doesn't replay it. Change revealSignature when you want the wave again, say after a filter changes. :animate="false" and reduced motion both draw the bins 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.

The default fills are mixes of --chart-1 into --muted, so changing --chart-1 recolors the whole scale. The hovered hexagon is redrawn slightly larger with a --chart-foreground outline.

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

Accessibility

The chart is announced as an image named by ariaLabel ("Hexbin chart" by default). The bins carry no text, so put the pattern a reader should notice in ariaDescription.

Each bin takes keyboard focus in turn, left to right, and shows its tooltip as it does on hover. On a touch screen, tap a bin.

API reference

Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).

HexbinChart

HexbinCells

HexbinGrid

HexbinXAxis

HexbinYAxis

HexbinTooltip

HexbinLegend