Dumbbell

A dumbbell compares values within each category: a dot per value on the value axis, joined by a connector from the smallest to the largest. It shows the gap between groups, such as pay by sex across roles or life expectancy across two years.

The dumbbell ships as its own package, @graphysdk/geom-dumbbell, on a 0.x version line. While it is on 0.x, a minor release may change its aesthetics, style parts or look; pin a caret range (^0.1.0) to take only patches. Tell us what works and what doesn’t on Discord.

Install

npm install @graphysdk/geom-dumbbell

pnpm add @graphysdk/geom-dumbbell

yarn add @graphysdk/geom-dumbbell

bun add @graphysdk/geom-dumbbell

Its only peer dependencies are @graphysdk/react and React. Register the plugin once with createGraphyKit, which adds kit.geom.dumbbell() and binds kit.GraphProvider to the same plugin:

import {
  createGraphyKit,
  GraphRenderer,
  highlight,
  styles,
} from '@graphysdk/react';
import { dumbbell } from '@graphysdk/geom-dumbbell';

const kit = createGraphyKit({ plugins: [dumbbell] });

Long data: one row per dot

Map the category to x, the value to y and the group to color. The geom groups the dots of each category itself, so the legend, palette, tooltip order and highlights all come from the color scale:

const data = {
  columns: [{ key: 'role' }, { key: 'sex' }, { key: 'salary' }],
  rows: [
    { role: 'Product', sex: 'Women', salary: 125 },
    { role: 'Product', sex: 'Men', salary: 140 },
    { role: 'Eng', sex: 'Women', salary: 118 },
    { role: 'Eng', sex: 'Men', salary: 132 },
    // …
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'role', y: 'salary', color: 'sex' }),
  kit.geom.dumbbell(),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.discrete()
);

export function PayGap() {
  return (
    <kit.GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </kit.GraphProvider>
  );
}

A dumbbell encodes position, not length, so the value axis fits the data instead of holding zero as a bar axis does, and the gaps read at full width. A category with one dot draws the dot and no connector. With three or more dots, the connector spans the smallest to the largest and the others sit on it. Leave color unmapped and every dot takes the default geom color, with no legend. The layer’s position is always 'identity': the geom groups a category’s dots itself, and 'dodge' or 'stack' is rejected with UNSUPPORTED_POSITION.

Wide data

When each group is its own column, reshape it to long in the spec:

const data = {
  columns: [{ key: 'region' }, { key: '1970' }, { key: '2020' }],
  rows: [
    { region: 'Europe', 1970: 71, 2020: 81 },
    { region: 'Africa', 1970: 45, 2020: 61 },
    // …
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'region', y: 'years', color: 'year' }),
  kit.transform.reshape({
    keep: ['region'],
    reshape: ['1970', '2020'],
    keyName: 'year',
    valueName: 'years',
  }),
  kit.geom.dumbbell(),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.discrete(),
  kit.coord.flip()
);

Horizontal

Add kit.coord.flip(), as for a horizontal bar. The categories move to the vertical axis and the connectors lie across.

Styling

The dots are the layer’s observations and are styled through the geom’s own builder. The connector is a part with a builder of its own:

Builder	Properties	Default
`kit.style.geom.dumbbell()`	`fill`, `stroke`, `alpha`, `fillAlpha`, `strokeAlpha`, `saturation`, `size`, `strokeWidth`	Fill from the scale, 10px, white border
`kit.style.geom.dumbbell.connector()`	`stroke`, `alpha`, `strokeWidth`, `dashArray`	A neutral gray, 2px, solid

const spec = kit.pipe(
  // …
  styles({
    defaults: [
      kit.style.geom.dumbbell({ size: 14, strokeWidth: 2 }),
      kit.style.geom.dumbbell.connector({ strokeWidth: 6, stroke: '#d9d4c7' }),
    ],
  })
);

An entry that names no part, such as style.geom({ fill: 'navy' }), styles the dots like any other geom’s observations and never the connector. The connector takes no color from the scale: it joins dots of different groups, so a scale color would be arbitrary. A connector entry’s where is tested against the category’s first dot, so write it against what every dot of the category shares, such as its x.

Hover and highlight

Hovering a category emphasizes its whole dumbbell. The tooltip lists every dot in legend order, with the dot nearest the cursor marked in place. A highlight matches dots. A connector is raised only when every dot it joins is raised: highlighting one group raises that group’s dots and no connector; highlighting one category raises its whole dumbbell.

const spec = kit.pipe(
  // …
  highlight({ variable: 'role', eq: 'Eng' })
);

Data labels

dataLabels.showDataLabels prints every dot’s value beside it. Under the default position: 'auto' each label sits on the far side of its dot from the connector, so the gap the chart is read from stays clear. An explicit position puts every label on the side justify names, for a chart that wants them in a row.

const spec = kit.pipe(
  // …
  kit.geom.dumbbell({ dataLabels: { showDataLabels: true } })
);

The label prints the dot’s y, formatted as the value axis formats it; map label to print another column instead. showStackTotals and showCategoryLabels are bar settings and a dumbbell places neither.

Not yet supported

The editor’s chart-type picker and the chart agent. In annotate mode the dumbbell renders, hovers, selects and takes annotations on its dots, but it is authored in code.
Aggregation. Duplicate rows for one category and group all draw; aggregate them first with transform.aggregate().

Get Started

Core concepts

Chart types

Rendering

Editing

Themes

Annotations & emphasis

Configuration

Advanced

Extending

Install

Long data: one row per dot

Wide data

Horizontal

Styling

Hover and highlight

Data labels

Not yet supported