@itsnyx/react-native-kline-chart

High-performance candlestick (K-Line) chart component for React Native with interactive drawing tools, technical indicators, and real-time data support.

Features

• Native rendering on both iOS (Swift) and Android (Java) at 60fps
• Smooth pinch-to-zoom, scroll, and vertical price-axis zoom
• Long-press crosshair with animated info panel
• Real-time data updates via modelArray prop (WebSocket-friendly)
• Infinite scroll for loading historical candles (onEndReached)
• Main-chart overlays (multi-select, combine freely): MA, EMA, BOLL, SAR, AVL, VWAP, Supertrend, and Ichimoku Cloud (with Kumo cloud fill)
• Sub-chart oscillators: VOL, MACD, KDJ, RSI, WR plus ROC, CCI, OBV, StochRSI, MFI, DMI, DMA, MTM, EMV
• Candle styles: all-solid, all-hollow, up-hollow, down-hollow, OHLC bars
• Coordinate types: linear, percentage, logarithmic, and inverted axis (Android)
• 15 drawing tools: trend lines, horizontal/vertical lines, rays, channels, rectangles, parallelograms, text annotations, price lines, time lines, candle markers, rulers, and more
• Drawing persistence: save and restore drawItemList across sessions
• Dark and light themes with full color customization
• Configurable candle width, padding, fonts, and layout ratios
• React Native New Architecture and Fabric compatible

Installation

npm install @itsnyx/react-native-kline-chart
# or
yarn add @itsnyx/react-native-kline-chart

iOS

cd ios && pod install

Android

No additional setup required.

Quick Start

import RNKLineView from '@itsnyx/react-native-kline-chart';

const optionList = JSON.stringify({
  modelArray: candleData,
  shouldScrollToEnd: true,
  targetList: { /* indicator params */ },
  configList: { /* visual config */ },
  drawList: { drawType: 0 },
});

<RNKLineView
  style={{ flex: 1 }}
  optionList={optionList}
  onEndReached={() => { /* load older candles */ }}
  onDrawItemComplete={(e) => { /* save drawing */ }}
/>

For a complete working example with all features (theme switching, indicator controls, drawing toolbar, data processing), see example/App.tsx.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | optionList | string | Yes | JSON string with chart config, data, indicators, and drawings | | modelArray | string | No | JSON string of data array only, for efficient real-time updates | | onDrawItemDidTouch | function | No | Called when user touches an existing drawing | | onDrawItemComplete | function | No | Called when a drawing is finished, returns full drawing object | | onDrawPointComplete | function | No | Called when a drawing point is placed | | onEndReached | function | No | Called when user scrolls to left edge (load more history) | | onNewOrder | function | No | Called with the hovered price when user triggers a new order action | | onCrosshairChange | function | No | Fired when configList.hoverInfoMode === "topLayer": instead of drawing a hover panel, the chart reports the selected candle so the app can render the OHLC readout itself. Payload: { visible, index, time, id, open, high, low, close, volume } (visible: false clears it) |

optionList Structure

{
  modelArray: [...],          // candle data array
  shouldScrollToEnd: true,    // scroll to latest candle on load
  targetList: {...},          // indicator parameters
  configList: {...},          // visual/theme configuration
  drawList: {...},            // drawing tools configuration
}

Data Format (modelArray items)

Each candle object should contain:

| Field | Type | Description | |-------|------|-------------| | id | number | Timestamp (ms) | | open | number | Opening price | | high | number | Highest price | | low | number | Lowest price | | close | number | Closing price | | vol | number | Volume |

Additional computed fields for indicators (maList, bollMb, bollUp, bollDn, macdValue, macdDif, macdDea, kdjK, kdjD, kdjJ, rsiList, wrList) and display fields (dateString, selectedItemList) should be pre-calculated before passing to the component. See example/App.tsx for the full processing pipeline.

configList

| Property | Type | Description | |----------|------|-------------| | colorList | { increaseColor, decreaseColor } | Bull/bear candle colors (use processColor()) | | mainOverlays | string[] | Extra main-chart overlays to draw in addition to MA/BOLL: any of "ema", "avl", "vwap", "super", "sar". Each candle in modelArray must carry the matching pre-computed field(s): emaList ([{value,title}]), avl, vwap, superTrend + superTrendUp, sar. Missing/NaN values are skipped safely. | | targetColorList | number[] | Colors for indicator lines | | backgroundColor | number | Chart background | | textColor | number | Axis text color | | gridColor | number | Grid line color | | mainFlex | number | Main chart height ratio (0.6-0.85) | | volumeFlex | number | Volume chart height ratio (0.15-0.25) | | showVolume | boolean | Show/hide volume section | | drawingsEditable | boolean | Whether existing drawings can be moved or edited by touch (default: true) | | itemWidth | number | Total candle slot width | | candleWidth | number | Candle body width | | fontFamily | string | Font for all text | | paddingTop / paddingBottom / paddingRight | number | Chart padding |

All color values should be passed through React Native's processColor().

New in v0.4 — overlays, oscillators, styles & coordinates

These fields extend the payload to unlock the full indicator set. See example/App.tsx + example/indicators.js for an end-to-end reference.

configList.mainOverlays — string[]. Main-chart overlays drawn in addition to the single primary MA/BOLL slot, so any combination shows together. Ids: "ma", "boll", "ema", "avl", "vwap", "super", "sar", "ichi", "resist". Each candle in modelArray must carry the matching pre-computed field(s): maList, emaList, bollUp/bollMb/bollDn, avl, vwap, superTrend+superTrendUp, sar, ichiTenkan/ichiKijun/ichiSpanA/ichiSpanB/ichiChikou, and resistR/resistS (support & resistance levels, drawn in the bear/bull colors — added in 0.4.1).

configList.ichiFuture — { a: number|null, b: number|null }[] (added in 0.4.8, along with indicators rendering in line/minute mode). Ichimoku future kumo: the raw Senkou Span A/B pairs of the last displacement window (typically 26 bars), projected past the newest candle. Entry k is drawn k+1 bars after the last candle, continuing the cloud into the right-side overscroll space (scroll right at the chart's end to reveal it). Send null for a span that has no value yet. Omit (or send []) to disable — e.g. when the ichi overlay is off. See computeICHI in example/indicators.js for how to build it.

configList.candleStyle — "allSolid" | "allHollow" | "upHollow" | "downHollow" | "ohlc".

configList.coordinateType — "linear" | "percentage" | "log" (Android). Percentage is relative to the first candle's open; log is guarded against non-positive values.

configList.invertedView — boolean (Android). Flips the main price axis.

Sub-chart oscillators — the built-ins use second = 3 MACD / 4 KDJ / 5 RSI / 6 WR. The nine extra oscillators use second codes >= 100 and render through one generic panel: send secondLabel (e.g. "ROC") at the top level and attach a subLines array — [{ value, title }] — to each candle. Codes: ROC 100, CCI 101, OBV 102, StochRSI 103, MFI 104, DMI 105, DMA 106, MTM 107, EMV 108.

targetList (Indicator Parameters)

| Parameter | Default | Description | |-----------|---------|-------------| | maList | [{day:5}, {day:10}, {day:30}] | MA periods | | bollN / bollP | "20" / "2" | Bollinger Bands period and multiplier | | macdS / macdL / macdM | "12" / "26" / "9" | MACD fast/slow/signal | | kdjN / kdjM1 / kdjM2 | "9" / "3" / "3" | KDJ parameters | | rsiList | [{day:6}, {day:12}, {day:24}] | RSI periods | | wrList | [{day:6}, {day:10}] | Williams %R periods |

drawList

| Property | Type | Description | |----------|------|-------------| | drawType | number | Active drawing tool (see Drawing Types below) | | drawItemList | array | Previously saved drawings to restore | | drawShouldContinue | boolean | Keep drawing mode active after completing one | | shouldClearDraw | boolean | Clear all drawings | | shouldFixDraw | boolean | Finalize current drawing | | drawColor | number | Drawing stroke color | | drawLineHeight | number | Drawing stroke width |

Drawing Types

| Value | Tool | |-------|------| | 0 | None (disable drawing) | | 1 | Trend line (segment) | | 2 | Horizontal line | | 3 | Vertical line | | 4 | Ray | | 5 | Channel (parallel lines) | | 101 | Rectangle | | 102 | Parallelogram | | 201 | Text annotation | | 301 | Global price line | | 302 | Global time line | | 303 | Price line with labels | | 304 | Candle marker | | 305 | Right horizontal line with label | | 306 | Ruler |

Real-time Updates

For streaming data (WebSocket, polling), update only the data without re-sending the full config:

<RNKLineView
  optionList={initialConfig}    // set once
  modelArray={JSON.stringify(liveData)}  // update on each tick
/>

Infinite Scroll

<RNKLineView
  onEndReached={() => {
    // fetch older candles, prepend to your data array,
    // and update modelArray — scroll position is preserved
  }}
/>

Drawing Persistence

onDrawItemComplete returns a full drawing object you can serialize:

{
  index, drawType, drawColor, drawLineHeight,
  drawDashWidth, drawDashSpace, drawIsLock,
  pointList: [{ x, y }],
  // text-only fields:
  text, textColor, textBackgroundColor, textCornerRadius,
}

Pass saved drawings back via drawList.drawItemList to restore them.

Locking Drawings

Set drawingsEditable: false in configList to make all existing drawings non-interactive. Touch passes through to normal chart scrolling — drawings are still displayed but cannot be moved or selected.

configList: {
  drawingsEditable: false,  // lock — drawings are view-only
  // drawingsEditable: true, // default — drawings can be moved/edited
}

A common pattern is to show drawings as read-only by default and toggle editing on when the user activates a drawing toolbar:

const [editingDrawings, setEditingDrawings] = React.useState(false);

const optionList = JSON.stringify({
  configList: {
    drawingsEditable: editingDrawings,
  },
  drawList: {
    drawType: editingDrawings ? DrawTypeConstants.show : DrawTypeConstants.none,
  },
});

Acknowledgments

This project is a fork of react-native-kline-view by @hellohublot, which itself was inspired by KChartView by @tifezh.

The upstream project is no longer actively maintained. This fork includes significant additions and fixes:

• Additional drawing tools (price lines, time lines, candle markers, rulers, text annotations with background/border-radius)
• Drawing lock support (drawIsLock)
• Scroll position preservation when prepending historical data
• Dynamic date formatting based on timeframe
• Hover panel improvements (volume formatting, border removal)
• Right price label coloring based on candle direction
• Vertical zoom gesture fixes on Android
• iOS/Android scroll interference fixes
• Various stability and performance improvements

License

Apache License 2.0 - see LICENSE.