# Combo Chart (/docs/charts/components/combo)

Use a combo chart when related measures read best as different marks, like actual values as bars against a target line, or when two measures need their own scales.

<Example caption="Hover a month, or focus the chart and press the arrow keys, to see every measure for it.">
<Basic />

```tsx
"use client";

import { ComboChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { month: "Jan", capacity: 960, shipped: 640, target: 700 },
  { month: "Feb", capacity: 960, shipped: 730, target: 720 },
  { month: "Mar", capacity: 1040, shipped: 780, target: 760 },
  { month: "Apr", capacity: 1040, shipped: 860, target: 820 },
  { month: "May", capacity: 1120, shipped: 920, target: 880 },
  { month: "Jun", capacity: 1120, shipped: 1020, target: 960 },
];

const units = (value: unknown) => `${value} units`;

const config = {
  capacity: { label: "Capacity", color: "#b2a0ef", formatValue: units },
  shipped: { label: "Shipped", color: "#733bff", formatValue: units },
  target: { label: "Target", color: "#0f8b8d", formatValue: units },
} satisfies SeriesConfig;

export default function ProductionChart() {
  return (
    <ComboChart
      data={data}
      config={config}
      animate
      margin={{ right: 16 }}
      aria-label="Monthly units shipped against capacity and target"
    >
      <ComboChart.Grid />
      <ComboChart.XAxis dataKey="month" />
      <ComboChart.YAxis width={48} />
      <ComboChart.Area dataKey="capacity" type="stepAfter" fillOpacity={0.2} />
      <ComboChart.Bar dataKey="shipped" maxBarSize={32} radius={[4, 4, 0, 0]} />
      <ComboChart.Line dataKey="target" strokeWidth={2} strokeDasharray="6 4" dot={false} />
      <ComboChart.Tooltip />
      <ComboChart.Legend />
    </ComboChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/combo-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
ComboChart
├── ComboChart.Background
├── ComboChart.Grid
├── ComboChart.XAxis
├── ComboChart.YAxis
├── ComboChart.Area
├── ComboChart.Bar
│   ├── ComboChart.Cell
│   └── ComboChart.Labels
├── ComboChart.Line
├── ComboChart.Scatter
├── ComboChart.Tooltip
├── ComboChart.Legend
└── ComboChart.Content
```

`ComboChart` holds the data, the series config and the accessible name, and draws only the parts you add. Add one `ComboChart.Area`, `ComboChart.Bar`, `ComboChart.Line` or `ComboChart.Scatter` per measure. `ComboChart.Cell` colors a single bar and `ComboChart.Labels` writes values on a series. They share the x-axis, the tooltip and the legend, which read their labels, colors and value formats from `config`. `ComboChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Series [#series]

Each series takes the same props as its own chart: `ComboChart.Bar` as in [Bar Chart](./bar.mdx), `ComboChart.Line` as in [Line Chart](./line.mdx), and `ComboChart.Area` as in [Area Chart](./area.mdx). Series draw in the order you add them, so put areas first and lines last to keep the lines on top.

Set `formatValue` in `config` so the tooltip shows each measure in its unit.

### Two Axes [#two-axes]

When measures have different units, give each its own `ComboChart.YAxis` with a `yAxisId`, and point each series at its axis with the same `yAxisId`. Set `orientation="right"` on the second axis, and `stackId` on bars that add up:

<Example caption="Press Retail in the legend to highlight its bars, then hover a month to compare revenue with margin.">
<TwoAxes />

```tsx
"use client";

import { ComboChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { month: "Jan", retail: 42000, wholesale: 26000, margin: 18 },
  { month: "Feb", retail: 47000, wholesale: 28000, margin: 20 },
  { month: "Mar", retail: 44000, wholesale: 34000, margin: 19 },
  { month: "Apr", retail: 52000, wholesale: 31000, margin: 23 },
  { month: "May", retail: 58000, wholesale: 36000, margin: 25 },
  { month: "Jun", retail: 63000, wholesale: 39000, margin: 27 },
];

const dollars = (value: unknown) => `$${Number(value).toLocaleString("en-US")}`;
const compactDollars = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  notation: "compact",
});

const config = {
  retail: { label: "Retail", color: "#733bff", formatValue: dollars },
  wholesale: { label: "Wholesale", color: "#b2a0ef", formatValue: dollars },
  margin: { label: "Margin", color: "#0f8b8d", formatValue: (value) => `${value}%` },
} satisfies SeriesConfig;

export default function RevenueMarginChart() {
  return (
    <ComboChart
      data={data}
      config={config}
      animate
      aria-label="Monthly revenue by channel in US dollars, with margin percentage on the right axis"
    >
      <ComboChart.Grid />
      <ComboChart.XAxis dataKey="month" />
      <ComboChart.YAxis yAxisId="revenue" width={48} tickFormatter={compactDollars.format} />
      <ComboChart.YAxis
        yAxisId="margin"
        orientation="right"
        width={40}
        domain={[0, 40]}
        tickFormatter={(value: number) => `${value}%`}
      />
      <ComboChart.Bar dataKey="retail" yAxisId="revenue" stackId="revenue" maxBarSize={32} />
      <ComboChart.Bar dataKey="wholesale" yAxisId="revenue" stackId="revenue" maxBarSize={32} />
      <ComboChart.Line dataKey="margin" yAxisId="margin" strokeWidth={2} dot={false} />
      <ComboChart.Tooltip />
      <ComboChart.Legend />
    </ComboChart>
  );
}
```
</Example>

Read each series against its own axis: equal heights don't mean equal values. Give each axis a `tickFormatter` with its unit so readers can tell them apart.

### Percentage Stacks [#percentage-stacks]

Set `stackOffset="expand"` to show each stack as shares of 100%. Keep the raw values in `data`, and use `createPercentStack` to label the axis and tooltip as percentages:

```tsx
import { ComboChart, createPercentStack } from "@kind-ui/charts";

const percent = createPercentStack({
  values: (entry) => [entry.payload.online, entry.payload.store],
});

<ComboChart stackOffset="expand" {...props}>
  <ComboChart.YAxis domain={[0, 1]} tickFormatter={percent.tickFormatter} />
  <ComboChart.Bar dataKey="online" stackId="share" />
  <ComboChart.Bar dataKey="store" stackId="share" />
  <ComboChart.Tooltip normalizedValue={percent.normalizedValue} />
</ComboChart>
```

`values` returns the raw values in the inspected entry's stack. If readers can hide series, return only the visible ones. For values that are already fractions, use `formatPercent` instead.

### Legend and Keyboard [#legend-and-keyboard]

Pressing a legend item highlights its series and dims the others, and screen readers hear "Highlighted Retail." Press it again, or press Escape, to clear it. To hide and show series from the legend instead, see [Legend](../building-blocks/legend.mdx).

Focus the chart and press the arrow keys to move between categories, which shows the tooltip with every measure, and Escape to dismiss it.

### Motion [#motion]

Series appear at once unless you set `animate`. Pass `true` and lines and areas draw in from left to right while bars grow from the axis. Pass options to change the shared direction and duration, and `lineReveal`, `areaReveal` or `barReveal` to override one type, or `false` to skip it:

```tsx
<ComboChart
  animate={{ revealDurationMs: 800, lineReveal: { revealDirection: "right-to-left" }, barReveal: false }}
  {...props}
>
```

When the reader prefers reduced motion, every series appears without animating. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder plot that sweeps across, or holds still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default). The legend and tooltip come back when `loading` turns off:

```tsx
<ComboChart loading={isPending} loadingLabel="Loading production" {...props}>
```

### Background [#background]

Add `ComboChart.Background` for a decorative pattern behind the plot: `pinpoints`, `crossings` or `waves`. It adds nothing to the tooltip, legend or accessible name.

```tsx
<ComboChart.Background pattern="pinpoints" opacity={0.15} />
```

## API Reference [#api-reference]

### ComboChart [#combochart]

### ComboChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                                               |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                                                  |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                                                        |
| `animate?`               | `boolean \| ComboAnimation \| undefined`                                                                                                                                                                                                             | Draws the bars, lines and areas in on mount. Pass `true` or options to change the timing per series type. Reduced motion skips it. Default: `false` |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                             |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                          |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                                            |
| `emphasis?`              | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                                                     |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                                             |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                                        |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                               |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                                 |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                              |
| `data?`                  | `ChartData<unknown> \| undefined`                                                                                                                                                                                                                    | The rows to plot. Each series reads its `dataKey` from every row.                                                                                   |

### ComboAnimation [#comboanimation]

### ComboRevealOptions

| Prop          | Type                                      | Description                                                                                 |
| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------- |
| `lineReveal?` | `false \| DirectionalReveal \| undefined` | Overrides the shared direction, duration or easing for lines. `false` skips their entrance. |
| `areaReveal?` | `false \| DirectionalReveal \| undefined` | Overrides the shared direction, duration or easing for areas. `false` skips their entrance. |
| `barReveal?`  | `false \| Reveal \| undefined`            | Overrides the shared duration or easing for bars. `false` skips their entrance.             |

<Caption>
`ComboChart` also takes every prop of Recharts' [ComposedChart](https://recharts.github.io/en-US/api/ComposedChart/), like `margin`, `layout` and `stackOffset`. The series take the props listed on [Bar Chart](./bar.mdx), [Line Chart](./line.mdx) and [Area Chart](./area.mdx).
</Caption>