Getting Started

Installation

npm install react-candlesticks

You can also view the package on npm, browse the GitHub repository, or visit the project website.

Basic Usage

Import Chart and configure it with at least one panel and layer. The only required props are data, and either panels or child <Panel> components. granularity can be omitted when your data uses a consistent interval and contains at least two data points. For loading states, empty datasets, single-point datasets, or irregularly spaced data, pass granularity explicitly.

import {
  Chart,
  Panel,
  Candlesticks
} from 'react-candlesticks';
import 'react-candlesticks/style.css';

const data = [
  { time: '2022-05-19', open: 707, high: 734, low: 694.11, close: 709, volume: 3029807 },
  // ...
];

const MyChart = () => {
  return (
    <Chart granularity="d1" data={data}>
      <Panel id="price">
        <Candlesticks />
      </Panel>
    </Chart>
  );
};

Tip: if your chart may render before data has loaded, set granularity explicitly to avoid inference errors on empty or single-point datasets.

Adding More Panels and Indicators

Panels stack vertically. Use heightRatio to control relative panel heights. Overlay indicators like <SMA> directly inside the price panel, or add separate panels for oscillators.

import { Chart, Panel, Candlesticks, SMA, VolumeBars, Stochastic } from 'react-candlesticks';

<Chart granularity="d1" data={data}>
  <Panel id="price" heightRatio={3}>
    <Candlesticks />
    <SMA period={20} />
    <SMA period={50} />
  </Panel>
  <Panel id="volume">
    <VolumeBars />
  </Panel>
  <Panel id="rsi">
    <Stochastic kPeriod={14} />
  </Panel>
</Chart>

Theming

Pass theme="light" or theme="dark" to use a built-in theme, or provide a custom Theme object.

<Chart theme="dark" granularity="d1" data={data}>
  ...
</Chart>

import type { Theme } from 'react-candlesticks';

const customTheme: Theme = {
  // ... custom theme properties
};

<Chart theme={customTheme} granularity="d1" data={data}>
  ...
</Chart>

Minimal Mode (For Lists and Thumbnails)

Use renderMode="minimal" when rendering many small charts per screen (for example watchlist rows). This mode defaults crosshairs, grid, xAxis, borders, enableScroll, and enableZoom to false, while still allowing you to override any of them explicitly.

<Chart
  renderMode="minimal"
  pixelRatio={1}
  width={120}
  height={60}
  data={data}
>
  <Panel id="mini-price">
    <Candlesticks yAxis={false} legend={false} />
  </Panel>
</Chart>

Scale Smoothing

Enable scaleSmoothing to soften abrupt y-axis rescaling while panning or zooming through changing price ranges.

<Chart granularity="d1" data={data} scaleSmoothing>
  <Panel>
    <Candlesticks />
  </Panel>
</Chart>

For more control, pass a ScaleSmoothingConfig.

Imperative Controls

Use a ChartHandle ref when buttons, filters, or external UI need to move the chart viewport or crosshair.

import { useRef } from 'react';
import type { ChartHandle } from 'react-candlesticks';

const chartRef = useRef<ChartHandle>(null);

<Chart ref={chartRef} granularity="d1" data={data}>
  <Panel>
    <Candlesticks />
  </Panel>
</Chart>

chartRef.current?.scrollToLatest({ marginBars: 8 });

Data Format

Each data point must conform to the DataPoint interface:

interface DataPoint {
  time: string;  // ISO 8601 UTC string, e.g. '2022-05-19T09:30:00Z' or '2022-05-19'
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

Sample data is available at Daily Data if you want to get started without a live data source.

Next Steps

• Browse Examples for common use cases
• See ChartProps for all available chart options
• See PanelConfig for panel configuration
• See LayerConfig for all layer types and their options
• Build a chart-scoped indicator with the Custom Indicator example
• Add chart-scoped annotations with Custom Drawings
• Try the live demo