Candlestick Chart API

Complete API reference for the Candlestick Chart, including data format, configuration options, custom parts, and context methods.

Data Format

Each row represents one candlestick with OHLC values. The xKey specifies which field to use for the x-axis (e.g. date, timestamp, or numeric index).

type CandlestickChartRow = Record<string, unknown> & {
  open: number;
  high: number;
  low: number;
  close: number;
};

type CandlestickChartData<TRow extends CandlestickChartRow = CandlestickChartRow> = {
  rows: TRow[];
  xKey: keyof TRow & string;
};

AG Style Config

Candlestick

Property	Type	Default	Description
candlestick.upColor	string	"rgba(255,255,255,0.98)"	Fill color for up candles (close > open).
candlestick.downColor	string	"rgba(91,132,196,0.35)"	Fill color for down candles (close < open).
candlestick.wickColor	string	"#5b84c4"	Color of the wick (high–low line).

Custom Parts

Override any visual element by providing a custom builder function: (args, context) => Widget

Part	Args	Description
candlestickBox	{ candlestick: Widget; candle: CandlestickChartCandle; geometry: CandlestickChartGeometry; index: number; isHovered: boolean }	Wrapper around each candlestick, providing layout alignment and sizing.
candlestick	{ candle: CandlestickChartCandle; geometry: CandlestickChartGeometry; index: number; isHovered: boolean }	The visual candlestick element (wick + body).
tooltip	{ label: string; items: { legend: string; color: string; value: number \| string }[] }	Tooltip content widget.
xAxis	{ line: Widget; labels: Widget[]; tick: Widget }	The complete x-axis assembly.
yAxis	{ line: Widget; labels: Widget[]; tick: Widget }	The complete y-axis assembly.
xAxisLabel	{ name: string; index: number }	Individual x-axis label.
yAxisLabel	{ name: string; index: number }	Individual y-axis label.
xAxisTick	undefined	X-axis tick mark.
yAxisTick	undefined	Y-axis tick mark.
dataView	{ candlesticks: Widget[] }	Container for all candlesticks in the data area.
layout	{ title: Widget; legends: Widget[]; plot: Widget }	Top-level layout composing title, legends, and the plot area.
plot	{ xAxis: Widget; yAxis: Widget; dataView: Widget; grid: Widget; axisCorner: Widget; tooltipArea: Widget }	The plot area composing axes, data view, grid, and tooltip.
tooltipArea	{ tooltip: Widget \| null; hoveredCandlestick: { index: number; candle: CandlestickChartCandle; x: number; y: number; width: number; height: number } \| null }	Tooltip positioning area that manages tooltip display.
legend	{ name: string; index: number; isVisible: boolean }	Individual legend item.
title	undefined	Chart title element.
dataLabel	{ value: number; label: string; legend: string }	Data label displayed near a candlestick.
xAxisLine	undefined	X-axis line.
yAxisLine	undefined	Y-axis line.
axisCorner	undefined	Corner element where x and y axes meet.
grid	{ xLine: Widget; yLine: Widget }	Grid container for horizontal and vertical grid lines.
gridXLine	undefined	Individual vertical grid line.
gridYLine	undefined	Individual horizontal grid line.

Context: `CandlestickChartContext`

Available in every custom builder via the second argument.

Name	Type	Kind	Description
data	CandlestickChartData	property	Current chart data.
candles	CandlestickChartCandle[]	property	Computed candlestick data from raw rows.
xTicks	CandlestickChartTick[]	property	Computed x-axis tick labels.
xValueType	"date" \| "number" \| "string"	property	Detected type of x-axis values.
transform	CandlestickChartTransform	property	Current transform options.
width	number	property	Current chart width in pixels.
height	number	property	Current chart height in pixels.
scale	CandlestickChartScale \| null	property	Computed scale with min, max, and step.
hoveredCandlestick	{ index: number; anchorKey: GlobalKey } \| null	property	Currently hovered candlestick info.
config	TConfig	property	The resolved chart configuration object.
setSize(width, height)	(width: number, height: number) => void	method	Update chart dimensions.
hoverCandlestick(index, anchorKey)	(index: number, anchorKey: GlobalKey) => void	method	Set hover state on a specific candlestick.
unhoverCandlestick(index)	(index: number) => void	method	Clear hover if the specified candlestick is currently hovered.
unhoverAllCandlesticks()	() => void	method	Clear all candlestick hover state.
isCandlestickHovered(index)	(index: number) => boolean	method	Check if a specific candlestick is hovered.

Custom Part Example

import { CandlestickChart } from "@/components/flitter/charts/candlestick-chart";

<CandlestickChart
  data={{
    rows: bitcoinRows,
    xKey: "date",
  }}
  config={{
    candlestick: {
      upColor: "#22c55e",
      downColor: "#ef4444",
      wickColor: "#6b7280",
    },
  }}
/>