react-klinecharts

A flexible React wrapper for KlineCharts with hooks, declarative sub-components, and full TypeScript support.

Live Demo

• Declarative props for all reactive chart settings
• <KLineChart.Indicator> and <KLineChart.Overlay> sub-components
• useKLineChart, useIndicator, useOverlay, useChartEvent hooks
• Full imperative access via ref
• Re-exports all klinecharts types and utilities
• Zero extra dependencies (native ResizeObserver)

Installation

pnpm add react-klinecharts
# or
npm install react-klinecharts

Peer dependencies: react >= 17, react-dom >= 17.

Quick Start

import { KLineChart, type Chart } from "react-klinecharts";
import { useRef } from "react";

function App() {
  const chartRef = useRef<Chart>(null);

  const data = [
    { timestamp: 1680000000000, open: 28000, high: 28500, low: 27800, close: 28200, volume: 100 },
    // ...
  ]

  return (
    <KLineChart
      ref={chartRef}
      data={data}
      symbol={{ ticker: "BTC/USDT" }}
      period={{ type: "minute", span: 15 }}
      style={{ width: "100%", height: 600 }}
    >
      <KLineChart.Indicator value={{ name: "MA", calcParams: [5, 10, 30] }} />
      <KLineChart.Indicator value="VOL" paneOptions={{ height: 80 }} />
    </KLineChart>
  );
}

API Reference

<KLineChart>

The core component. Manages chart lifecycle, provides context for hooks and sub-components.

All standard HTML div attributes (className, style, id, etc.) are passed through to the container element.

Init-only Props

Prop	Type	Description
options	Options	Chart initialization options. Applied once on mount.

Data Props

Prop	Type	Description
data	KLineData[]	Static data array to apply to the chart.
dataLoader	DataLoader	Data loader with getBars, subscribeBar, unsubscribeBar. Calls setDataLoader.
symbol	SymbolInfo	Symbol info (ticker, precision). Calls setSymbol.
period	Period	Time period ({ type, span }). Calls setPeriod.

Reactive Props

These props are synced to the chart instance via useEffect. Changing them updates the chart without re-initialization.

Prop	Type	Chart Method
styles	string | DeepPartial<Styles>	setStyles()
locale	string	setLocale()
timezone	string	setTimezone()
formatter	Partial<Formatter>	setFormatter()
thousandsSeparator	Partial<ThousandsSeparator>	setThousandsSeparator()
decimalFold	Partial<DecimalFold>	setDecimalFold()
zoomEnabled	boolean	setZoomEnabled()
scrollEnabled	boolean	setScrollEnabled()
zoomAnchor	ZoomAnchorType | Partial<ZoomAnchor>	setZoomAnchor()
offsetRightDistance	number	setOffsetRightDistance()
maxOffsetLeftDistance	number	setMaxOffsetLeftDistance()
maxOffsetRightDistance	number	setMaxOffsetRightDistance()
leftMinVisibleBarCount	number	setLeftMinVisibleBarCount()
rightMinVisibleBarCount	number	setRightMinVisibleBarCount()
barSpace	number	setBarSpace()

Event Callbacks

Prop	Description
onReady	(chart: Chart) => void — fired after chart initialization
onZoom	Chart zoom event
onScroll	Chart scroll event
onVisibleRangeChange	Visible data range changed
onCrosshairChange	Crosshair position changed
onCandleBarClick	Candle bar clicked
onPaneDrag	Pane drag event
onCandleTooltipFeatureClick	Candle tooltip feature clicked
onIndicatorTooltipFeatureClick	Indicator tooltip feature clicked
onCrosshairFeatureClick	Crosshair feature clicked

<KLineChart.Indicator>

Declarative indicator management. Renders nothing — purely manages indicator lifecycle.

<KLineChart.Indicator
  value={{ name: "MA", calcParams: [5, 10, 30] }}
  isStack={false}
  paneOptions={{ height: 100 }}
/>

// Or simply by name:
<KLineChart.Indicator value="VOL" />

Prop	Type	Description
value	string | IndicatorCreate	Indicator name or full config
isStack	boolean	Stack on existing indicators in same pane
paneOptions	PaneOptions	Options for the indicator pane

<KLineChart.Overlay>

Declarative overlay (drawing tool) management. Renders nothing — purely manages overlay lifecycle.

<KLineChart.Overlay
  value={{
    name: "segment",
    points: [
      { timestamp: 1234567890000, value: 100 },
      { timestamp: 1234567900000, value: 200 },
    ],
  }}
/>

Prop	Type	Description
value	string | OverlayCreate | Array<string | OverlayCreate>	Overlay config(s)

<KLineChart.Widget>

Declarative portal component that injects standard HTML/React elements directly into the chart DOM utilizing createPortal and the native chart.getDom() method.

<KLineChart.Widget paneId="candle" position="main">
  <div className="custom-tooltip">My interactive React tooltip!</div>
</KLineChart.Widget>

Prop	Type	Description
paneId	string	ID of the pane to inject into (e.g. "candle", "xAxis", or custom indicator pane IDs). If undefined, binds to root container.
position	"root" | "main" | "yAxis"	Layer position relative to the pane. Default is "main".

Hooks

useKLineChart()

Access the Chart instance from any descendant of <KLineChart>.

function MyComponent() {
  const chart = useKLineChart();
  // chart is Chart | null
  return <button onClick={() => chart?.scrollToRealTime()}>Go to now</button>;
}

useIndicator(options)

Manages indicator lifecycle. Creates on mount, removes on unmount, overrides on config change.

function MyIndicator() {
  const paneId = useIndicator({
    value: { name: "RSI", calcParams: [14] },
    paneOptions: { height: 80 },
  });
  return null;
}

useOverlay(options)

Manages overlay lifecycle. Creates on mount, removes on unmount, overrides on config change.

function MyOverlay() {
  const id = useOverlay({
    value: { name: "priceLine", points: [{ value: 50000 }] },
  });
  return null;
}

useChartEvent(type, callback)

Subscribe to chart action events with a stable ref-based handler.

function Logger() {
  useChartEvent("onCrosshairChange", (data) => {
    console.log("Crosshair:", data);
  });
  return null;
}

Available event types: "onZoom", "onScroll", "onVisibleRangeChange", "onCrosshairChange", "onCandleBarClick", "onPaneDrag", "onCandleTooltipFeatureClick", "onIndicatorTooltipFeatureClick", "onCrosshairFeatureClick".

Imperative API (ref)

For operations not covered by declarative props, use the Chart ref:

const chartRef = useRef<Chart>(null);

// Navigation
chartRef.current?.scrollToRealTime(300);
chartRef.current?.scrollToTimestamp(timestamp);
chartRef.current?.zoomAtCoordinate(1.5);

// Data queries
chartRef.current?.getDataList();
chartRef.current?.getVisibleRange();
chartRef.current?.getBarSpace();

// Coordinate conversion
chartRef.current?.convertToPixel(points, filter);
chartRef.current?.convertFromPixel(coordinates, filter);

// Export
chartRef.current?.getConvertPictureUrl(true, "png");

// DOM access
chartRef.current?.getDom(paneId, position);
chartRef.current?.getSize(paneId, position);

// Pane management
chartRef.current?.setPaneOptions(options);
chartRef.current?.getPaneOptions(id);

// Imperative indicator/overlay operations
chartRef.current?.createIndicator(value, isStack, paneOptions);
chartRef.current?.getIndicators(filter);
chartRef.current?.createOverlay(value);
chartRef.current?.getOverlays(filter);

See the full KlineCharts API documentation for all available methods.

Registration Functions

Module-level registration functions are re-exported from klinecharts:

import {
  registerIndicator,
  registerOverlay,
  registerFigure,
  registerLocale,
  registerStyles,
  registerXAxis,
  registerYAxis,
} from "react-klinecharts";

// Register a custom indicator
registerIndicator({
  name: "MyIndicator",
  calc: (dataList) => {
    return dataList.map((d) => ({ value: d.close }));
  },
  figures: [{ key: "value", title: "VAL: ", type: "line" }],
});

Type Re-exports

All klinecharts types are re-exported for convenience:

import type {
  Chart,
  KLineData,
  Styles,
  Options,
  Indicator,
  IndicatorCreate,
  Overlay,
  OverlayCreate,
  Crosshair,
  ActionType,
  ActionCallback,
  DataLoader,
  SymbolInfo,
  Period,
  // ... all klinecharts types
} from "react-klinecharts";

Examples

Custom Indicator with Hooks

function BollingerBands({ period = 20 }: { period?: number }) {
  useIndicator({
    value: { name: "BOLL", calcParams: [period, 2] },
  });
  return null;
}

function App() {
  const [period, setPeriod] = useState(20);

  return (
    <KLineChart dataLoader={loader} symbol={symbol} period={period_}>
      <BollingerBands period={period} />
    </KLineChart>
  );
}

Theming

<KLineChart
  dataLoader={loader}
  symbol={symbol}
  period={period}
  styles={{
    grid: { show: false },
    candle: {
      type: "area",
      area: {
        lineColor: "#2196F3",
        backgroundColor: [
          { offset: 0, color: "rgba(33, 150, 243, 0.3)" },
          { offset: 1, color: "rgba(33, 150, 243, 0)" },
        ],
      },
    },
  }}
/>

Custom Locale

import { registerLocale } from "react-klinecharts";

registerLocale("ru-RU", {
  time: "Время",
  open: "Откр.",
  high: "Макс.",
  low: "Мин.",
  close: "Закр.",
  volume: "Объём",
  change: "Изм.",
  turnover: "Оборот",
  second: "сек",
  minute: "мин",
  hour: "час",
  day: "дн",
  week: "нед",
  month: "мес",
  year: "год",
});

<KLineChart locale="ru-RU" ... />

Architecture

src/
  index.ts                    # Public API barrel export
  types.ts                    # React-specific types
  KLineChartContext.ts        # React context for chart instance
  KLineChart.tsx              # Core component
  hooks/
    useKLineChart.ts          # Context-based chart access
    useChartEvent.ts          # Event subscription hook
    useIndicator.ts           # Indicator lifecycle hook
    useOverlay.ts             # Overlay lifecycle hook
  components/
    Indicator.tsx             # <KLineChart.Indicator>
    Overlay.tsx               # <KLineChart.Overlay>

Design principles:

• Thin wrapper — never re-implements what klinecharts already does
• Reactive props drive useEffect calls to chart methods
• Ref escape hatch exposes the full Chart instance for imperative operations
• Context enables hooks and sub-components in descendants
• Stable event subscriptions — callbacks stored in refs, no re-subscribe churn
• Natural cleanup order — React unmounts children before parent, so indicators/overlays clean up before dispose()

Development

pnpm install
pnpm build          # Build library
pnpm dev            # Build in watch mode
pnpm typecheck      # TypeScript type check

# Run example
cd example
pnpm install
pnpm dev

License

MIT