# Composed Chart

Bars, lines and areas in one plot, with an optional second value axis.

- Category: Charts
- Page: https://wunderui.com/components/composed-chart
- Tier: Core and Pro

## Install

Composed Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ComposedChart, ComposedChartProps, ComposedChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ComposedChart } from "@wunderui/react/charts"

const data = [
  { month: "Jan", revenue: 32000, profit: 18000 },
  { month: "Feb", revenue: 41000, profit: 22000 },
  { month: "Mar", revenue: 38000, profit: 27000 },
  { month: "Apr", revenue: 47000, profit: 24000 },
]

export function RevenueAndProfit() {
  return (
    <ComposedChart
      data={data}
      index="month"
      series={[
        { key: "revenue", label: "Revenue" },
        { key: "profit", label: "Profit" },
      ]}
      label="Revenue and profit"
    />
  )
}
```

Expected result: You should see revenue as bars and profit as a line over the same grid, with the months below.

## When to use

### Use Composed Chart for

- A volume and a rate in one plot (revenue as bars, margin as a line)
- Two measures with different units on two value axes
- A target or a previous period drawn over bars
- A backdrop series such as activity under a line

### Use something else

- [Bar Chart](https://wunderui.com/components/bar-chart) for one measure per category
- [Line Chart](https://wunderui.com/components/line-chart) for trends only
- [Area Chart](https://wunderui.com/components/area-chart) for volumes only
- [Stacked Chart](https://wunderui.com/components/stacked-chart) for the parts of a total

## Keyboard

The plot is focusable, so the chart works without a pointer.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous category. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last category. |
| `Shift+ArrowRight` or `Shift+ArrowLeft` | Extends a selected range from the point you started on. A range is only selected when `onSelectedRangeChange` is set. |
| `Escape` | Clears the active point and the selected range. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

What the chart does on its own and what the page decides.

- **Series types:** Each series can set its own type. Without one, the first series is a bar and the others are lines, or areas in the bar and area variant.
- **Second axis:** A series on the right axis is measured on its own scale over the same grid lines. Use it only for a different unit.
- **Draw order:** Series are drawn in order, so lines stay on top of bars and areas. A backdrop bar series sits under everything.
- **Tooltip:** Each visible series gets a row, in series order. For mixed units, format the number so it reads well for both.
- **Loading, empty and error:** Loading shows a shimmering skeleton, empty and error show a centred message, and error adds a Try again button when a retry handler is set. The card never changes height.
- **Legend:** A ChartCard shows the series as badges. With two or more, each badge toggles its series off (the last visible one stays on), and a static legend works for roles.
- **Data table:** The chart also renders its data as a table for screen readers, in plot order. A ChartCard can show that table on screen through a toggle that keeps the card height.
- **Size:** The chart fills the width of its container, and a height setting controls the plot. Text never scales, so labels keep their size at every width.

## Motion

The enter sequence and the hover follow the motion tokens of the library.

- **Draw-in:** Bars grow from zero while areas and lines wipe in from the left, and each point on a line appears as the line reaches it. It plays the first time the chart is in view, after loading and when the data changes.
- **Hover:** The hovered category keeps its strength and the bars and points of the others dim. Lines and areas get a ringed point per series on their own axis.
- **Reduced motion:** With reduced motion the chart appears at once. The tooltip, the crosshair and every state still work.

## Anatomy

- `ComposedChart`: Takes the data, the index key and a list of series. Each series picks bar, line or area and the left or right axis, and a bar series can sit behind the others as a backdrop.
- `Plot`: The focusable region. Arrow keys walk the categories; the hover shows a muted band with a bar series, otherwise a crosshair.
- `Grid and axes`: One set of grid lines serves both axes. The right axis has its own scale on the same lines, and its labels start at the plot edge so the two never share a label.
- `Bars, areas and lines`: Bars grow from zero, areas wipe in and lines draw along their path, with lines always on top. A backdrop bar series sits under the areas and lines.
- `Active points`: One ringed point per line or area series on the hovered category, placed on that series' own axis. Bar series show the hover band instead.
- `Tooltip`: One row per visible series, in series order. Keep the series in one unit family, or format the number so it reads right in both cases.
- `Loading, empty and error`: The skeleton is bar-shaped when any series is a bar, and line-shaped otherwise.
- `Data table and live region`: A table for screen readers with a column per series, plus a live region that announces the active category.

## Best practices

### When to use

- Use ComposedChart when an amount and a rate or target share the same categories, such as monthly revenue as bars and margin as a line. Otherwise use two separate charts.

### Do

- Put the second measure on the right axis only when its unit differs. Say in the card description which series reads against which axis.
- Draw amounts as bars and rates as lines, and stay at three series. Every extra type adds another visual rule to learn.
- Give the right axis its own formatter so labels carry their unit, such as a percent sign. Without one they reuse the left formatter and a rate reads as 3.1k.

### Don't

- Don't use two axes to make unrelated lines look correlated, since rescaling can make any two series follow each other. With no real link, use two charts.
- Don't cover bars with an opaque area. Put the bar series behind the others, or use the bar and line pattern, so the bars stay readable.

## API reference

### ComposedChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per category / point. |
| index* | string |  | Field holding the category label (x axis; y axis for horizontal bars). |
| series* | readonly ComposedSeries[] |  |  |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  | Enter sequence (draw, wipe, grow) on scroll into view, after loading and on new data. Default true; off with reduced motion. |
| animationKey | string \| number |  | Change it to play the enter sequence again (e.g. `useChartReload().version`). New `data` replays it by itself. |
| aspectRatio | number |  | Width ÷ height when `height` is not set. Default 2.6. |
| axisFormatter | ChartValueFormatter |  | Value-axis labels; defaults to `valueFormatter`. |
| categoryAxis | boolean |  | Category-axis labels (default true). |
| categoryFormatter | (label: string) => string |  | Shortens category labels on the axis, e.g. "Mar 12" → "Mar"; tooltip and pill keep the full label. |
| categoryTicks | readonly string[] |  | Only these category labels are shown on the axis (the rest stay hoverable). |
| className | string |  | Extra classes for the root element of the chart. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| defaultSelectedRange | ChartRange \| null |  | The range that is selected at first, for an uncontrolled chart. |
| description | string |  | Screen-reader summary; generated from the data when omitted. |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| grid | boolean |  | Grid lines (default true). |
| gridFade | boolean |  | The grid fades out towards both ends (default true). |
| gridIntervals | number |  | Number of equal grid intervals. Default: one per 44 px of plot height, capped by the size class (xs 2, sm 3, md 3, lg 4, xl 5). |
| gridStyle | "solid" \| "dashed" |  | Grid lines are dashed 4 / 4 by default; `solid` draws them through. |
| height | number |  | Fixed height of the plot frame in px. Without it the height follows the width (`aspectRatio`, `minHeight`, `maxHeight`): 220 px on a phone, up to 434 px (the plot of the Figma large card) from about 1130 px wide. |
| hiddenSeries | readonly string[] |  | Series keys that are switched off (legend toggle): drawn faded, dimmed in the tooltip. |
| includeZero | boolean |  | The value axis starts at 0 (owner rule, default). `false` fits the data (prices, temperatures). |
| label | string |  | Accessible name, e.g. the card title. |
| maxHeight | number |  | Highest height from `aspectRatio`. Default 434. |
| minHeight | number |  | Lowest height from `aspectRatio`. Default 220. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| onSelectedRangeChange | (range: ChartRange \| null) => void |  | Called when a drag across the plot or Shift with an arrow key changes the range, and with `null` when Escape or a click clears it. |
| rangeSelectable | boolean |  | Allow selecting a range by dragging or Shift + arrow keys. On when `onSelectedRangeChange` is set. |
| resolution | "auto" \| "full" |  | `auto` (default): lines and areas draw at most 1.5 points per pixel (LTTB; hover and tooltip keep every point), and bars on a time axis that would get thinner than they may are gathered into weeks, months … `full` draws every point and eve… |
| rightAxisDomain | readonly number[] |  | Values that bound the right axis (default: the right-axis series). |
| rightAxisFormatter | (v: number) => string |  | Labels of the right axis (dual axis). |
| selectedRange | ChartRange \| null |  | The selected range as inclusive indices `[from, to]` into `data`, to control it yourself. `null` selects nothing. |
| state | "ready" \| "loading" \| "empty" \| "error" |  | `loading` shows the chart-shaped skeleton, `empty` and `error` a message in the plot. |
| tooltip | boolean |  | Tooltip on hover / keyboard focus. Default true. |
| tooltipTitle | (datum: ChartDatum, index: number) => React.ReactNode |  | Title line of the tooltip; defaults to the category label. |
| valueAxis | boolean |  | Value-axis labels (default true). Off for compact cards and sparkline-like plots. |
| valueAxisPlacement | "auto" \| "outside" \| "inside" |  | Where the value labels go: `outside` left of the plot, `inside` in the plot above their grid lines (saves the label column on narrow charts). `auto` (default) puts them left of the plot at every size; `inside` is opt-in. |
| valueAxisSide | "left" \| "right" |  | Side of the value axis (vertical charts). `right` is the price axis of trading charts. |
| valueDomain | readonly [number, number] |  | Fix the value domain instead of fitting it to the data (still rounded to nice steps). |
| valueFormatter | ChartValueFormatter |  | Values in tooltip, labels, table and live region. Default: 42000 → "42k". |
| valueTicks | readonly number[] |  | Exact value-axis ticks (ascending), e.g. [0, 10000, … 70000]; replaces the nice-step domain. |
| variant | "bar-line" \| "bar-area" \| "area-line-dual-axis" \| "bar-line-markers" | "bar-line" | Figma variant. Default `bar-line`. |
| width | number |  | Fixed width instead of filling and measuring the container. |
| xScale | "band" \| "time" |  | `band` (default): the categories sit side by side in equal bands. `time`: the `index` field holds dates (Date, ms or a string such as "2026-03-01"); points sit at their real distance, the axis picks its tick level (hours → days → weeks → m… |

## Examples

### States

### Table view

## In context

### Orders and Conversion Rate

Orders per week as bars, conversion rate as a line on the right axis.

### Revenue and Margin

Monthly revenue bars with the gross margin line on its own axis.

### Ad Spend and ROAS

Daily ad cost as bars, return on ad spend as a marked line.

## For AI agents

`get_component("composed-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
