# DumbbellChart

> Two or more values per category joined by a bar: the length of the line is the spread, the change is last minus first.

Source: https://ui.jcsoftdev.com/docs/components/dumbbell-chart

Two or more values per category joined by a bar: the length of the line is
the spread, the change is last minus first. Rows run top to bottom, or
columns left to right with `orientation="vertical"`; use `sort` to rank by change.

## Import

```ts
import { DumbbellChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/dumbbell-chart`.

## Usage

```tsx
<DumbbellChart
  title="Citas por servicio: mes pasado contra este mes"
  items={citas}
  fromLabel="Mes pasado"
  toLabel="Este mes"
  valueFormat="integer"
  sort="none"
  rowHeight={38}
  delta="absolute"
  valueLabels
  lowerIsBetter={false}
  grid
  legend
  tooltip
  loading={false}
  animate
  deltaLabel="Cambio"
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly DumbbellItem[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `fromLabel` | `string` | `"Before"` | Name of the first value (the left dot), e.g. "Mes pasado". |
| `toLabel` | `string` | `"After"` | Name of the second value (the right dot), e.g. "Este mes". |
| `fromColor` | `string` |  |  |
| `toColor` | `string` |  |  |
| `measures` | `readonly DumbbellMeasure[]` |  | Names and colors of the dots when rows have `values`; the first and last are compared by the change. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | "vertical" draws a column per category with the dots stacked on the value axis. |
| `valueFormat` | `ValueFormat` |  |  |
| `sort` | `"none" \| "delta" \| "abs-delta" \| "to"` | `"none"` | Order of the rows; "delta" puts the biggest increase first. |
| `rowHeight` | `number` | `38` | Height of every row in pixels (default 38), horizontal only. |
| `height` | `number \| "fill"` |  | Height of the drawing in pixels, or `"fill"` to take the height of the parent. Horizontal rows stretch to it; by default they size themselves. |
| `aspectRatio` | `number` |  | Width / height ratio; stretches the rows to fit it. |
| `delta` | `false \| "percent" \| "absolute"` | `"absolute"` | Change (last minus first value) printed next to each row. `false` hides it. |
| `valueLabels` | `boolean` | `true` | Writes the values next to the dots (default true). |
| `lowerIsBetter` | `boolean` | `false` | Colors the change green when it goes down (e.g. cancellations or waiting time). |
| `xAxis` | `ValueAxisOptions` |  | Axis of the values (bottom axis, or left axis when vertical). |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `deltaLabel` | `string` | `"Change"` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-dumbbellchart--default)
- [Ranked By Change](/storybook/?path=/story/charts-dumbbellchart--ranked-by-change)
- [Revenue](/storybook/?path=/story/charts-dumbbellchart--revenue)
- [Lower Is Better](/storybook/?path=/story/charts-dumbbellchart--lower-is-better)
- [Columns](/storybook/?path=/story/charts-dumbbellchart--columns)
- [Three Measures](/storybook/?path=/story/charts-dumbbellchart--three-measures)
- [Three Measures Columns](/storybook/?path=/story/charts-dumbbellchart--three-measures-columns)
- [Loading](/storybook/?path=/story/charts-dumbbellchart--loading)
- [Empty](/storybook/?path=/story/charts-dumbbellchart--empty)
- [Narrow](/storybook/?path=/story/charts-dumbbellchart--narrow)

## Source

`packages/ui/src/charts/dumbbell-chart/dumbbell-chart.tsx`