# Candlestick Chart

Candlestick chart for prices: candles, hollow candles, OHLC bars, volume, moving averages, Heikin-Ashi, an order-book depth chart and Renko, on a right-hand price axis.

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

## Install

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

## Import

```tsx
import { CandlestickChart, CandlestickChartProps, CandlestickChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

const data = [
  { date: "Jul 1", open: 42, high: 44.1, low: 41.2, close: 43.5 },
  { date: "Jul 2", open: 43.5, high: 45.3, low: 43, close: 44.8 },
  { date: "Jul 3", open: 44.8, high: 45, low: 42.6, close: 43.1 },
]

export function TokenPrice() {
  return <CandlestickChart data={data} index="date" label="WUI / USD" />
}
```

Expected result: You see three candles with wicks, green where the close is above the open, and the price axis on the right.

## When to use

### Use Candlestick Chart for

- Prices over time with open, high, low and close
- A price chart with volume or moving averages
- An order book as a depth chart
- Renko bricks or Heikin-Ashi candles to filter noise

### Use something else

- [Line Chart](https://wunderui.com/components/line-chart) for one price series without ranges per period
- [Bar Chart](https://wunderui.com/components/bar-chart) for volumes and plain comparisons
- [Range Bar Chart](https://wunderui.com/components/range-bar-chart) for a span that is not a price
- [Sparkline](https://wunderui.com/components/sparkline) for a tiny trend next to a price

## 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 candle. 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 candle. |
| `Shift+ArrowRight` or `Shift+ArrowLeft` | Extends a selected range from the candle you started on. The range pill and the live region give the move from the first open to the last close with its percentage. Needs `rangeSelectable`. |
| `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.

- **Field names:** Each row supplies open, high, low, close and volume. Other field names can be mapped, a row with a missing price is skipped, not drawn as zero, and numbers follow the reader's locale unless a locale or a formatter is set.
- **Up and down:** A candle is green when the close is above the open and red below. Hollow candles outline the rising ones and fill the falling ones, so direction survives without colour.
- **Price axis:** The price axis sits on the right and fits the data, with no zero baseline. Volume bars take the bottom fifth, and only the depth chart starts at 0.
- **Overlays:** Moving averages default to windows of 7 and 21, and Renko takes a brick size. The depth chart plots cumulative bids left of the spread and asks right.
- **Narrow charts:** When a candle would get thinner than 4 px, neighbouring candles are bundled into one: the first open, the highest high, the lowest low and the last close, with the volume summed. The tooltip names the bundled rows, and full resolution keeps every candle.
- **Loading, empty and error:** The chart keeps its size while loading, empty or failed, so the card never jumps. Add a retry handler to show a Try again button on error.
- **Legend:** A ChartCard shows the series as badges. With two or more, each badge switches its series off and the last visible one stays on, and a legend of roles can be made static.
- **Size:** The chart fills the width of its container, and you set the plot height. Text never scales, so labels keep their size at every width.

## Motion

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

- **Enter:** Candles and OHLC bars open from their middle, left to right, volume bars grow from the bottom, and moving averages and the depth chart wipe in. It plays when the chart first comes into view, after loading and when the data changes.
- **Hover:** The active candle keeps its strength and the others dim, while the tooltip shows open, high, low and close.
- **Reduced motion:** With reduced motion the chart appears at once. The tooltip, crosshair and every state still work.

## Anatomy

- `CandlestickChart`: Takes data and an index field, and reads open, high, low, close and volume by those names. Moving averages, the Renko brick size and the order-book fields are set by props.
- `Plot`: The focusable region: arrow keys walk the candles, and Shift with an arrow selects a range. A pill and a live region report the move from the first open to the last close.
- `Grid and axes`: The price axis sits on the right without a zero baseline, except in the depth chart. With volume the bars take the bottom fifth, and the depth chart plots bids left of the spread and asks right.
- `Candles`: A body from open to close with a wick from low to high, or an OHLC bar. Green is up and red is down, and hollow candles keep the direction readable without colour.
- `Moving averages and volume`: Moving average lines (orange, then purple) and grey volume bars, each in its own chart type.
- `Tooltip`: The date with open, high, low and close, plus volume when it is shown.
- `Loading, empty and error`: A skeleton, empty and error messages, as on the other charts. A row with a missing price is skipped, not drawn as zero.
- `Data table and live region`: Open, high, low, close and volume per period as a table for screen readers.

## Best practices

### When to use

- Use CandlestickChart for markets and any series with open, high, low and close per period. For a single price per period, LineChart is lighter and easier to read.

### Do

- Pass a value formatter with the currency and the right decimals, like $1,842.50. The default shows up to two decimals and no currency symbol.
- Add the volume bars rather than a second chart when volume explains the move. They share the time axis, so a spike lines up with its candle.
- Select a range with Shift and the arrows to read the price change over it. Keyboard users get the same figure as a mouse drag.

### Don't

- Don't rely on green and red alone. Use hollow candles or OHLC bars for print and red-green colour blindness, and keep the tooltip for exact values.
- Don't show Renko or Heikin-Ashi as the plain price. They are transformed series, so name the variant in the card title.

## API reference

### CandlestickChart

| 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). |
| 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. |
| ask | string | "ask" |  |
| aspectRatio | number |  | Width ÷ height when `height` is not set. Default 2.6. |
| axisFormatter | ChartValueFormatter |  | Value-axis labels; defaults to `valueFormatter`. |
| bid | string | "bid" | `depth-chart`: fields of the order book rows (price = `index`). Defaults: bid, ask. |
| brickSize | number |  | `renko`: price move per brick (default: a twelfth of the price range, rounded). |
| 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. |
| close | string | "close" |  |
| 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. |
| high | string | "high" |  |
| 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. |
| locale | string |  | Locale of the default number formats for prices, depth and volume, such as en-US. Without it the numbers follow the reader's locale, and a value formatter replaces the price format. |
| low | string | "low" |  |
| maxHeight | number |  | Highest height from `aspectRatio`. Default 434. |
| minHeight | number |  | Lowest height from `aspectRatio`. Default 220. |
| movingAverages | readonly number[] | DEFAULT_MOVING_AVERAGES | `candles-moving-average`: window lengths of the moving averages. Default [7, 21]. |
| 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. |
| open | string | "open" | Fields of the OHLC rows. Defaults: open, high, low, close, volume. |
| 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… |
| 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 | "candles" \| "hollow-candles" \| "ohlc" \| "candles-volume" \| "candles-moving-average" \| "heikin-ashi" \| "depth-chart" \| "renko" | "candles" | Figma variant. Default `candles`. |
| volume | string | "volume" |  |
| 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

## In context

### Order Book

Depth of the book with the spread next to it.

## For AI agents

`get_component("candlestick-chart")`

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