react-klinecharts-ui

v0.3.0

Published

2 months ago

Headless React components for building financial trading terminals with klinecharts

0High
0Medium
0Low

nemezzizz

react klinecharts trading financial terminal headless chart candlestick indicators drawing-tools

react-klinecharts-ui — Library Reference

react-klinecharts-ui is a headless React library for building financial trading terminals on top of klinecharts. It provides a state provider, a set of hooks, and overlay templates. No UI components are included — use any UI framework you prefer.

Live Demo

Acknowledgments

Many features in this library — including 11 TradingView-style indicators, 9 drawing overlays, the TA math library, undo/redo, layout manager, and script editor — were ported from the QUANTIX Extended Edition fork of KLineChart-Pro by @dsavenk0. The original fork implements these as a tightly-coupled Vue 3 application; this library re-implements them as headless React hooks following the composable, framework-agnostic architecture.

Installation

npm install react-klinecharts-ui react-klinecharts
# or with pnpm
pnpm add react-klinecharts-ui react-klinecharts
# or with yarn
yarn add react-klinecharts-ui react-klinecharts

Concept

The library follows a headless pattern — all UI is written by the consumer. The library is responsible for:

State management — current symbol, period, theme, indicators, timezone, screenshots
Datafeed integration — abstract interface for loading historical data and subscribing to real-time updates
klinecharts overlay management — indicators, drawing tools, order lines
Utilities — createDataLoader, overlay templates

All hooks must be called inside <KlinechartsUIProvider>.

KlinechartsUIProvider

The root provider. Wraps the application and supplies the context.

import { KlinechartsUIProvider } from "react-klinecharts-ui";

<KlinechartsUIProvider
  datafeed={myDatafeed}
  defaultSymbol={{ ticker: "BTCUSDT", pricePrecision: 2 }}
  defaultTheme="dark"
  overlays={[orderLine]}
  onSymbolChange={(symbol) => saveToStorage("symbol", symbol)}
>
  <App />
</KlinechartsUIProvider>;

Props

| Prop | Type | ------------------------ | datafeed | defaultSymbol | defaultPeriod | defaultTheme | defaultTimezone | defaultMainIndicators | defaultSubIndicators | defaultLocale | periods | styles | registerExtensions | overlays | onStateChange | onSymbolChange | onPeriodChange | onThemeChange | onTimezoneChange | onMainIndicatorsChange | onSubIndicatorsChange | onSettingsChange | Default | Description | | ---------------------------------------------- | ------------------ | ---------------------------------------------------------------- | | Datafeed | — | Required. Datafeed interface implementation | | PartialSymbolInfo | null | Initial trading instrument | | TerminalPeriod | First in periods | Initial timeframe | | string | "light" | Initial theme ("light" or "dark") | | string | "Asia/Shanghai" | Initial timezone (IANA) | | string[] | ["MA"] | Indicators on the main chart at startup | | string[] | ["VOL"] | Indicators on sub-panels at startup | | string | "en-US" | Locale passed to klinecharts | | TerminalPeriod[] | DEFAULT_PERIODS | List of available timeframes | | DeepPartial<Styles> | — | Custom klinecharts styles (applied when the chart is ready) | | boolean | true | Whether to register built-in drawing overlays | | OverlayTemplate[] | — | Additional overlay templates (e.g. orderLine, custom overlays) | | (action, nextState, prevState) => void | — | Called synchronously on every dispatched action | | (symbol) => void | — | Called when the symbol changes | | (period) => void | — | Called when the period changes | | (theme) => void | — | Called when the theme changes | | (timezone) => void | — | Called when the timezone changes | | (indicators: string[]) => void | — | Called when main indicators change | | (indicators: Record<string, string>) => void | — | Called when sub-indicators change | | (settings: Record<string, unknown>) => void | — | Called when settings change via useKlinechartsUISettings |

Overlay registration

The provider registers overlays once on mount via useRef — passing an inline array is safe and does not cause re-registration:

// Safe — does not re-register on every render
<KlinechartsUIProvider overlays={[orderLine, myCustomOverlay]}>

Types

Datafeed

Data interface implemented by the consumer.

interface Datafeed {
  /**
   * Search symbols by a query string.
   * signal — AbortSignal to cancel the request when a newer query is typed.
   */
  searchSymbols(
    search: string,
    signal?: AbortSignal,
  ): Promise<PartialSymbolInfo[]>;

  /**
   * Load historical bars.
   * from/to — timestamps in milliseconds.
   * When from=0, load the most recent available data.
   */
  getHistoryKLineData(
    symbol: SymbolInfo,
    period: TerminalPeriod,
    from: number,
    to: number,
  ): Promise<KLineData[]>;

  /**
   * Subscribe to real-time updates.
   * callback is called for every new bar.
   */
  subscribe(
    symbol: SymbolInfo,
    period: TerminalPeriod,
    callback: (data: KLineData) => void,
  ): void;

  /** Unsubscribe from real-time updates. */
  unsubscribe(symbol: SymbolInfo, period: TerminalPeriod): void;
}

PartialSymbolInfo

Minimal description of a trading instrument.

interface PartialSymbolInfo {
  ticker: string; // e.g. "BTCUSDT", "AAPL", "EUR/USD"
  pricePrecision?: number; // Decimal places for price display
  volumePrecision?: number; // Decimal places for volume display
  [key: string]: unknown; // Any additional fields
}

KlinechartsUIState

Complete provider state. Accessible via useKlinechartsUI().state.

interface KlinechartsUIState {
  chart: Chart | null; // klinecharts Chart instance (null before onReady)
  datafeed: Datafeed; // The datafeed passed to the provider
  symbol: PartialSymbolInfo | null; // Current symbol
  period: TerminalPeriod; // Current timeframe
  theme: string; // Current theme: "light" | "dark"
  timezone: string; // Current timezone (IANA)
  isLoading: boolean; // true while data is loading
  locale: string; // klinecharts locale ("en-US")
  periods: TerminalPeriod[]; // List of available timeframes
  mainIndicators: string[]; // Active main chart indicators
  subIndicators: Record<string, string>; // Active sub-indicators: { name → paneId }
  styles: DeepPartial<Styles> | undefined; // Custom klinecharts styles
  screenshotUrl: string | null; // URL of the last screenshot
}

KlinechartsUIAction

Union type of all possible actions for dispatch.

type KlinechartsUIAction =
  | { type: "SET_CHART"; chart: Chart }
  | { type: "SET_SYMBOL"; symbol: PartialSymbolInfo }
  | { type: "SET_PERIOD"; period: TerminalPeriod }
  | { type: "SET_THEME"; theme: string }
  | { type: "SET_TIMEZONE"; timezone: string }
  | { type: "SET_LOADING"; isLoading: boolean }
  | { type: "SET_MAIN_INDICATORS"; indicators: string[] }
  | { type: "SET_SUB_INDICATORS"; indicators: Record<string, string> }
  | { type: "SET_STYLES"; styles: DeepPartial<Styles> | undefined }
  | { type: "SET_LOCALE"; locale: string }
  | { type: "SET_SCREENSHOT_URL"; url: string | null };

Hooks

useKlinechartsUI

The primary hook — returns the full context: state, dispatch, datafeed, and fullscreen ref.

const { state, dispatch, datafeed, onSettingsChange, fullscreenContainerRef } =
  useKlinechartsUI();

Return value:

interface KlinechartsUIContextValue {
  state: KlinechartsUIState;
  dispatch: Dispatch<KlinechartsUIAction>; // enhancedDispatch with synchronous callbacks
  datafeed: Datafeed;
  onSettingsChange?: (settings: Record<string, unknown>) => void;
  fullscreenContainerRef: RefObject<HTMLElement | null>;
}

Note: dispatch is enhancedDispatch. It synchronously computes the new state by calling the pure reducer directly and immediately invokes onStateChange / individual callbacks — without waiting for a React re-render.

useKlinechartsUITheme

Manage the chart theme.

const { theme, setTheme, toggleTheme } = useKlinechartsUITheme();

| Field | Type | Description | | ------------- | ------------------------- | ------------------------------------- | | theme | string | Current theme: "light" or "dark" | | setTheme | (theme: string) => void | Set a specific theme | | toggleTheme | () => void | Toggle between "light" and "dark" |

const { theme, toggleTheme } = useKlinechartsUITheme();

<button onClick={toggleTheme}>
  {theme === "dark" ? <SunIcon /> : <MoonIcon />}
</button>;

useKlinechartsUILoading

Loading state of chart data.

const { isLoading } = useKlinechartsUILoading();

| Field | Type | Description | | ----------- | --------- | ------------------------------------------------ | | isLoading | boolean | true while createDataLoader is fetching bars |

const { isLoading } = useKlinechartsUILoading();

{
  isLoading && <div className="spinner" />;
}

usePeriods

Manage timeframes.

const { periods, activePeriod, setPeriod } = usePeriods();

| Field | Type | Description | | -------------- | ---------------------------------- | --------------------------------- | | periods | TerminalPeriod[] | Full list of available timeframes | | activePeriod | TerminalPeriod | Currently selected timeframe | | setPeriod | (period: TerminalPeriod) => void | Change the timeframe |

TerminalPeriod extends KlinechartsPeriod with a label: string field.

Default timeframes: 1m, 5m, 15m, 1H, 2H, 4H, D, W, M, Y

const { periods, activePeriod, setPeriod } = usePeriods();

<div className="flex gap-1">
  {periods.map((p) => (
    <button
      key={p.label}
      onClick={() => setPeriod(p)}
      className={activePeriod.label === p.label ? "active" : ""}
    >
      {p.label}
    </button>
  ))}
</div>;

useTimezone

Manage the chart timezone.

const { timezones, activeTimezone, setTimezone } = useTimezone();

| Field | Type | Description | | ---------------- | ---------------------------- | ------------------------- | | timezones | TimezoneItem[] | Full list of timezones | | activeTimezone | string | Current IANA timezone key | | setTimezone | (timezone: string) => void | Change the timezone |

interface TimezoneItem {
  key: string; // IANA: "Europe/London", "America/New_York", "UTC"
  localeKey: string; // Short name: "london", "new_york", "utc"
}

Available timezones: UTC, Pacific/Honolulu, America/Juneau, America/Los_Angeles, America/Chicago, America/Toronto, America/Sao_Paulo, Europe/London, Europe/Berlin, Asia/Bahrain, Asia/Dubai, Asia/Ashkhabad, Asia/Almaty, Asia/Bangkok, Asia/Shanghai, Asia/Tokyo, Australia/Sydney, Pacific/Norfolk

const { timezones, activeTimezone, setTimezone } = useTimezone();

<select value={activeTimezone} onChange={(e) => setTimezone(e.target.value)}>
  {timezones.map((tz) => (
    <option key={tz.key} value={tz.key}>
      {tz.key}
    </option>
  ))}
</select>;

useSymbolSearch

Search and select a trading instrument.

const {
  query,
  results,
  isSearching,
  activeSymbol,
  setQuery,
  selectSymbol,
  clearResults,
} = useSymbolSearch(debounceMs);

| Parameter | Type | Default | Description | | ------------ | -------- | ------- | --------------------------------------------- | | debounceMs | number | 300 | Delay before calling datafeed.searchSymbols |

| Field | Type | Description | | -------------- | ------------------------------------- | --------------------------------------------- | | query | string | Current search query | | results | PartialSymbolInfo[] | Results from the last search | | isSearching | boolean | true while the request is in flight | | activeSymbol | PartialSymbolInfo \| null | Currently selected symbol from state.symbol | | setQuery | (q: string) => void | Update the query (triggers debounced search) | | selectSymbol | (symbol: PartialSymbolInfo) => void | Select a symbol — dispatches SET_SYMBOL | | clearResults | () => void | Clear search results |

The hook automatically cancels in-flight requests via AbortController on every new keystroke and on unmount.

const { query, results, isSearching, selectSymbol, setQuery } =
  useSymbolSearch(300);

<input
  value={query}
  onChange={(e) => setQuery(e.target.value)}
  placeholder="Search..."
/>;
{
  isSearching && <Spinner />;
}
{
  results.map((sym) => (
    <button key={sym.ticker} onClick={() => selectSymbol(sym)}>
      {sym.ticker}
    </button>
  ));
}

useIndicators

Full indicator management: add/remove, visibility, parameters, move between panes.

const {
  mainIndicators,
  subIndicators,
  activeMainIndicators,
  activeSubIndicators,
  availableMainIndicators,
  availableSubIndicators,
  addMainIndicator,
  removeMainIndicator,
  addSubIndicator,
  removeSubIndicator,
  toggleMainIndicator,
  toggleSubIndicator,
  moveToMain,
  moveToSub,
  setIndicatorVisible,
  updateIndicatorParams,
  getIndicatorParams,
  isMainIndicatorActive,
  isSubIndicatorActive,
} = useIndicators();

Fields

| Field | Type | Description | | ------------------------- | ------------------------ | ------------------------------------------ | | mainIndicators | IndicatorInfo[] | All main indicators with isActive flag | | subIndicators | IndicatorInfo[] | All sub-indicators with isActive flag | | activeMainIndicators | string[] | Active main indicator names only | | activeSubIndicators | Record<string, string> | Active sub-indicators: { name → paneId } | | availableMainIndicators | string[] | Full list from MAIN_INDICATORS | | availableSubIndicators | string[] | Full list from SUB_INDICATORS |

interface IndicatorInfo {
  name: string; // "MA", "MACD", "RSI", etc.
  isActive: boolean; // Whether it is currently on the chart
}

Methods

| Method | Description | | --------------------------------------------- | ------------------------------------------------------------- | | addMainIndicator(name) | Creates the indicator on candle_pane with id main_${name} | | removeMainIndicator(name) | Removes the indicator and updates state | | addSubIndicator(name) | Creates the indicator on a new sub-pane with id sub_${name} | | removeSubIndicator(name) | Removes the sub-indicator and its pane | | toggleMainIndicator(name) | add if inactive, remove if active | | toggleSubIndicator(name) | Same for sub-indicators | | moveToMain(name) | Moves from sub-pane to candle_pane | | moveToSub(name) | Moves from candle_pane to a new sub-pane | | setIndicatorVisible(name, isMain, visible) | Show/hide indicator via chart.overrideIndicator | | updateIndicatorParams(name, paneId, params) | Update calcParams via chart.overrideIndicator | | getIndicatorParams(name) | Returns [{ label, defaultValue }] or [] if no parameters | | isMainIndicatorActive(name) | Quick active check | | isSubIndicatorActive(name) | Quick active check |

Available indicators

Main chart (MAIN_INDICATORS): MA, EMA, SMA, BOLL, SAR, BBI

Sub-panes (SUB_INDICATORS): MA, EMA, VOL, MACD, BOLL, KDJ, RSI, BIAS, BRAR, CCI, DMI, CR, PSY, DMA, TRIX, OBV, VR, WR, MTM, EMV, SAR, SMA, ROC, PVT, BBI, AO

Indicators with configurable parameters: SMA, BOLL, SAR, BBI, MACD, KDJ, BRAR, CCI, DMI, CR, PSY, DMA, TRIX, OBV, VR, MTM, EMV, ROC, AO and others.

useDrawingTools

Manage drawing tools (chart overlays).

const {
  categories,
  activeTool,
  magnetMode,
  isLocked,
  isVisible,
  selectTool,
  clearActiveTool,
  setMagnetMode,
  toggleLock,
  toggleVisibility,
  removeAllDrawings,
} = useDrawingTools();

| Field/Method | Type | Description | | --------------------- | -------------------------------- | ------------------------------------------------------- | | categories | DrawingCategoryItem[] | Tool categories with nested tools | | activeTool | string \| null | Name of the last selected tool | | magnetMode | "normal" \| "weak" \| "strong" | Snap-to-OHLC mode | | isLocked | boolean | Whether all drawings are locked | | isVisible | boolean | Whether all drawings are visible | | selectTool(name) | — | Start drawing via chart.createOverlay | | clearActiveTool() | — | Deselect tool (local state only) | | setMagnetMode(mode) | — | Change magnet mode for all existing and future drawings | | toggleLock() | — | Toggle lock on all drawings | | toggleVisibility() | — | Show/hide all drawings | | removeAllDrawings() | — | Remove all drawings in the drawing_tools group |

interface DrawingToolItem {
  name: string; // klinecharts overlay name, e.g. "arrow", "fibonacciLine"
  localeKey: string; // Localization key
}

interface DrawingCategoryItem {
  key: string; // "singleLine" | "moreLine" | "polygon" | "fibonacci" | "wave"
  tools: DrawingToolItem[];
}

Categories and tools:

| Category (key) | Tools | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | singleLine | horizontalStraightLine, horizontalRayLine, horizontalSegment, verticalStraightLine, verticalRayLine, verticalSegment, straightLine, rayLine, segment, arrow, priceLine | | moreLine | priceChannelLine, parallelStraightLine | | polygon | circle, rect, parallelogram, triangle | | fibonacci | fibonacciLine, fibonacciSegment, fibonacciCircle, fibonacciSpiral, fibonacciSpeedResistanceFan, fibonacciExtension, gannBox | | wave | xabcd, abcd, threeWaves, fiveWaves, eightWaves, anyWaves |

useKlinechartsUISettings

Manage chart appearance: candle type, colors, price marks, axes, grid, crosshair, tooltips.

const settings = useKlinechartsUISettings();

State

| Field | Type | Default | Description | | ------------------------ | --------------- | ---------------- | ------------------------- | | candleType | string | "candle_solid" | Candle display type | | candleUpColor | string | "#2DC08E" | Bullish candle color | | candleDownColor | string | "#F92855" | Bearish candle color | | showLastPrice | boolean | true | Last price mark on Y-axis | | showHighPrice | boolean | true | High price mark | | showLowPrice | boolean | true | Low price mark | | showIndicatorLastValue | boolean | true | Indicator last value mark | | priceAxisType | PriceAxisType | "normal" | Y-axis scale type | | reverseCoordinate | boolean | false | Invert Y-axis | | showTimeAxis | boolean | true | Show X-axis | | showGrid | boolean | true | Show grid | | showCrosshair | boolean | true | Show crosshair | | showCandleTooltip | boolean | true | OHLCV tooltip | | showIndicatorTooltip | boolean | true | Indicator tooltip |

Candle types: candle_solid, candle_stroke, candle_up_stroke, candle_down_stroke, ohlc, area

Price axis types: "normal", "percentage", "log"

Extra fields

| Field | Type | Description | | ---------------- | --------------------------------------------- | ----------------------------------------------------- | | candleTypes | CandleTypeItem[] | List of { key, localeKey } for rendering a selector | | priceAxisTypes | { key: PriceAxisType; localeKey: string }[] | List for rendering a selector |

Setters

Each field has a corresponding setter: setCandleType, setCandleUpColor, setCandleDownColor, setShowLastPrice, setShowHighPrice, setShowLowPrice, setShowIndicatorLastValue, setPriceAxisType, setReverseCoordinate, setShowTimeAxis, setShowGrid, setShowCrosshair, setShowCandleTooltip, setShowIndicatorTooltip.

All setters immediately apply changes via chart.setStyles(...).

| Method | Description | | ------------------- | ----------------------------------------------------------- | | resetToDefaults() | Reset all settings to defaults via chart.setStyles(theme) |

Important: Settings are stored in local useState inside the hook — they are not part of the provider's reducer state. The hook must be called unconditionally (not only when a dialog is open) to preserve settings across dialog open/close cycles. Changes trigger onSettingsChange from the provider.

useScreenshot

Capture and download a chart screenshot.

const { screenshotUrl, capture, download, clear } = useScreenshot();

| Field/Method | Type | Description | | --------------------- | ----------------------------- | ------------------------------------------------------ | | screenshotUrl | string \| null | JPEG data URL of the last screenshot | | capture() | () => void | Capture the current chart state | | download(filename?) | (filename?: string) => void | Download as a file (default: "chart-screenshot.jpg") | | clear() | () => void | Clear screenshotUrl from state |

Screenshot is created via chart.getConvertPictureUrl(true, "jpeg", bgColor). Background depends on the current theme: #151517 for dark, #ffffff for light.

const { screenshotUrl, capture, download, clear } = useScreenshot();

<button onClick={capture}>Capture</button>;
{
  screenshotUrl && (
    <>
      <img src={screenshotUrl} alt="chart" />
      <button onClick={() => download()}>Download</button>
      <button onClick={clear}>Close</button>
    </>
  );
}

useFullscreen

Toggle fullscreen mode. Uses fullscreenContainerRef from the provider.

const { isFullscreen, toggle, enter, exit, containerRef } = useFullscreen();

| Field/Method | Type | Description | | -------------- | -------------------------------- | ------------------------------ | | isFullscreen | boolean | Current fullscreen state | | toggle() | () => void | Toggle | | enter() | () => void | Enter fullscreen | | exit() | () => void | Exit fullscreen | | containerRef | RefObject<HTMLElement \| null> | The same ref from the provider |

Supports cross-browser vendor prefixes (webkit, ms).

Important: containerRef must be assigned to the container element that should occupy the full screen (typically the root layout element):

const { containerRef, toggle, isFullscreen } = useFullscreen();

<div ref={containerRef as React.RefObject<HTMLDivElement>}>
  <button onClick={toggle}>{isFullscreen ? "Exit" : "Fullscreen"}</button>
  <ChartView />
</div>;

useOrderLines

Create and manage horizontal price level lines (order lines).

Requirement: The orderLine overlay must be registered via overlays={[orderLine]} on the provider.

const {
  createOrderLine,
  updateOrderLine,
  removeOrderLine,
  removeAllOrderLines,
} = useOrderLines();

createOrderLine

createOrderLine(options: OrderLineOptions): string | null

Returns the id of the created line, or null if the chart is not ready.

interface OrderLineOptions extends OrderLineExtendData {
  id?: string; // Auto-generated if omitted
  price: number; // Price level
  draggable?: boolean; // Allow drag to change price. Default: false
  onPriceChange?: (price: number) => void; // Called when drag ends
}

All OrderLineExtendData fields (see orderLine extension) are accepted directly — they flow through as overlay extendData.

updateOrderLine

updateOrderLine(id: string, options: Partial<Omit<OrderLineOptions, "id">>): void

Updates an existing line. Only pass the fields you want to change.

removeOrderLine / removeAllOrderLines

removeOrderLine(id: string): void
removeAllOrderLines(): void // Removes all overlays with name="orderLine"

const { createOrderLine, updateOrderLine, removeOrderLine } = useOrderLines();

const id = createOrderLine({
  price: 45000,
  color: "#ff9900",
  text: "Target",
  line: { style: "dashed" },
  mark: { bg: "#ff9900", color: "#fff" },
  draggable: true,
  onPriceChange: (newPrice) => console.log("Moved to:", newPrice),
});

updateOrderLine(id!, { color: "#00ff00" });
removeOrderLine(id!);

useUndoRedo

Undo/redo history for drawing overlays and indicator toggles. Automatically connected to useDrawingTools and useIndicators via a shared context ref — actions are recorded without manual wiring.

Keyboard shortcuts: Ctrl+Z (undo), Ctrl+Y / Ctrl+Shift+Z (redo).

import { useUndoRedo } from "react-klinecharts-ui";

const { canUndo, canRedo, undo, redo, pushAction, clear } = useUndoRedo();

Return type: `UseUndoRedoReturn`

| Property | Type | Description | |----------|------|-------------| | canUndo | boolean | Whether there are actions to undo | | canRedo | boolean | Whether there are actions to redo | | undo | () => void | Undo the last action | | redo | () => void | Redo the last undone action | | pushAction | (action: UndoRedoAction) => void | Push a new action onto the undo stack (clears redo) | | clear | () => void | Clear all undo/redo history |

Action types

| Type | Trigger | Undo behaviour | Redo behaviour | |------|---------|----------------|----------------| | overlay_added | User completes a drawing | Removes the overlay | Re-creates the overlay | | overlays_removed | removeAllDrawings() | Restores all removed overlays | Re-removes them | | indicator_toggled | Add/remove indicator | Reverses the toggle | Re-applies the toggle |

Cross-hook communication

useUndoRedo registers a pushAction callback on undoRedoListenerRef (shared via provider context). When useDrawingTools finishes a drawing or useIndicators toggles an indicator, they call the ref to record the action — no prop drilling required.

useLayoutManager

Save, load, rename, and delete named chart layouts via localStorage. Captures indicators, drawings, symbol, and period. Optional auto-save with 5-second debounce.

import { useLayoutManager } from "react-klinecharts-ui";

const {
  layouts,
  saveLayout,
  loadLayout,
  deleteLayout,
  renameLayout,
  refreshLayouts,
  autoSaveEnabled,
  setAutoSaveEnabled,
} = useLayoutManager();

Return type: `UseLayoutManagerReturn`

| Property | Type | Description | |----------|------|-------------| | layouts | LayoutEntry[] | List of saved layout entries | | saveLayout | (name: string) => string \| null | Save current chart state; returns layout ID | | loadLayout | (id: string) => boolean | Load and apply a layout by ID | | deleteLayout | (id: string) => void | Delete a layout | | renameLayout | (id: string, name: string) => boolean | Rename a layout | | refreshLayouts | () => void | Refresh the list from localStorage | | autoSaveEnabled | boolean | Whether auto-save is enabled | | setAutoSaveEnabled | (enabled: boolean) => void | Toggle auto-save |

LayoutEntry

interface LayoutEntry {
  id: string;
  name: string;
  symbol: string;
  period: string;
  timestamp: number;
  lastModified: number;
  state: ChartLayoutState;
}

ChartLayoutState

interface ChartLayoutState {
  version: string;
  meta: { symbol: string; period: string; timestamp: number; lastModified: number };
  indicators: Array<{ paneId: string; name: string; calcParams: any[]; visible: boolean }>;
  drawings: Array<{ name: string; points: any[]; styles?: any; extendData?: any }>;
}

useScriptEditor

Pine Script-style custom indicator editor. Users write plain JavaScript function bodies that receive TA, dataList (array of KLineData), and params (parsed from a comma-separated string). The script must return an array of objects — one per candle, each key becomes a chart series.

Scripts execute inside a sandboxed new Function() with dangerous globals shadowed: fetch, XMLHttpRequest, WebSocket, Worker, SharedWorker, importScripts, self, caches, indexedDB.

import { useScriptEditor } from "react-klinecharts-ui";

const {
  code, setCode,
  scriptName, setScriptName,
  params, setParams,
  placement, setPlacement,
  error, status, isRunning, hasActiveScript,
  runScript, removeScript, resetCode,
  exportScript, importScript,
  defaultScript,
} = useScriptEditor();

Return type: `UseScriptEditorReturn`

| Property | Type | Description | |----------|------|-------------| | code | string | Current script source code | | setCode | (code: string) => void | Update the source code | | scriptName | string | Display name of the script | | setScriptName | (name: string) => void | Update the name | | params | string | Comma-separated numeric params (e.g. "14, 26, 9") | | setParams | (params: string) => void | Update params | | placement | ScriptPlacement | "main" or "sub" | | setPlacement | (p: ScriptPlacement) => void | Set placement | | error | string | Last error message (empty = no error) | | status | string | Last status message | | isRunning | boolean | Whether the script is currently executing | | hasActiveScript | boolean | Whether a script indicator is on the chart | | runScript | () => void | Execute the script and register the indicator | | removeScript | () => void | Remove the current script indicator from the chart | | resetCode | () => void | Reset code to the default template | | exportScript | () => void | Download the code as a .js file | | importScript | (file: File) => void | Load a script from a file | | defaultScript | string | The default template code |

Example script

// Available: TA, dataList, params
const period = params[0] ?? 14;
const closes = dataList.map(d => d.close);
const highs  = dataList.map(d => d.high);
const lows   = dataList.map(d => d.low);

const rsi  = TA.rsi(closes, period);
const boll = TA.bollinger(closes, period, 2);

// Return one object per candle — each key = one line on the chart
return rsi.map((v, i) => ({
  rsi:   v,
  upper: boll.upper[i],
  mid:   boll.mid[i],
  lower: boll.lower[i],
}));

useWatchlist

Manage a list of tracked symbols with live price updates from your datafeed.

import { useWatchlist } from "react-klinecharts-ui";

const {
  items,
  addSymbol,
  removeSymbol,
  switchSymbol,
  activeSymbol,
} = useWatchlist();

Return type: `UseWatchlistReturn`

| Property | Type | Description | |----------|------|-------------| | items | WatchlistItem[] | Array of tracked symbols with price data | | addSymbol | (ticker: string) => void | Add a symbol to the watchlist | | removeSymbol | (ticker: string) => void | Remove a symbol from the watchlist | | switchSymbol | (ticker: string) => void | Change the chart to display a symbol | | activeSymbol | string \| null | Currently displayed symbol ticker |

WatchlistItem

| Property | Type | Description | |----------|------|-------------| | ticker | string | Symbol identifier | | lastPrice | number \| null | Last traded price | | change | number \| null | Absolute price change | | changePercent | number \| null | 24h percentage change |

useCompare

Compare multiple symbols on the same chart with individual colors and visibility toggle.

import { useCompare } from "react-klinecharts-ui";

const {
  symbols,
  addSymbol,
  removeSymbol,
  toggleSymbol,
  clearAll,
} = useCompare();

Return type: `UseCompareReturn`

| Property | Type | Description | |----------|------|-------------| | symbols | CompareSymbol[] | Array of comparison symbols with metadata | | addSymbol | (ticker: string) => void | Add a symbol to compare | | removeSymbol | (ticker: string) => void | Remove a comparison symbol | | toggleSymbol | (ticker: string) => void | Toggle visibility of a symbol | | clearAll | () => void | Remove all comparison symbols |

CompareSymbol

| Property | Type | Description | |----------|------|-------------| | ticker | string | Symbol identifier | | visible | boolean | Whether the symbol is currently visible on chart | | color | string | Hex color code for the symbol's line |

useMeasure

Measure price changes, percentage swings, bar count, and time intervals between two points on the chart.

import { useMeasure } from "react-klinecharts-ui";

const {
  isActive,
  startMeasure,
  cancelMeasure,
  result,
} = useMeasure();

Return type: `UseMeasureReturn`

| Property | Type | Description | |----------|------|-------------| | isActive | boolean | Whether measurement mode is enabled | | startMeasure | () => void | Enter measurement mode (click two points) | | cancelMeasure | () => void | Exit measurement mode | | result | MeasureResult \| null | Measurement data (null if not measured yet) |

MeasureResult

| Property | Type | Description | |----------|------|-------------| | priceDiff | number | Absolute price difference | | pricePercent | number | Percentage change | | bars | number | Number of bars between points | | timeDiff | number | Time difference in milliseconds |

useAnnotations

Add text annotations at specific price levels and timestamps with optional colors.

import { useAnnotations } from "react-klinecharts-ui";

const {
  annotations,
  addAnnotation,
  removeAnnotation,
  updateAnnotation,
  clearAnnotations,
} = useAnnotations();

Return type: `UseAnnotationsReturn`

| Property | Type | Description | |----------|------|-------------| | annotations | Annotation[] | Array of all annotations | | addAnnotation | (text, price, timestamp, color?) => string | Add annotation; returns ID | | removeAnnotation | (id: string) => void | Remove annotation by ID | | updateAnnotation | (id, updates) => void | Update text or color | | clearAnnotations | () => void | Remove all annotations |

Annotation

| Property | Type | Description | |----------|------|-------------| | id | string | Unique identifier | | text | string | Annotation text | | price | number | Price level | | timestamp | number | Candle timestamp | | color | string \| undefined | Optional hex color |

useReplay

Replay historical candles at various speeds with play/pause/step controls and progress tracking.

import { useReplay } from "react-klinecharts-ui";

const {
  isPlaying,
  speed,
  currentIndex,
  totalBars,
  play,
  pause,
  stop,
  step,
  setSpeed,
} = useReplay();

Return type: `UseReplayReturn`

| Property | Type | Description | |----------|------|-------------| | isPlaying | boolean | Whether replay is running | | speed | number | Current playback speed (0.25, 0.5, 1, 2, 4) | | currentIndex | number | Current bar index being displayed | | totalBars | number | Total bars in the dataset | | play | () => void | Start replay from current position | | pause | () => void | Pause replay (can resume with play) | | stop | () => void | Stop replay and reset to start | | step | () => void | Advance one bar when paused | | setSpeed | (speed: number) => void | Set playback speed multiplier |

Utilities

createDataLoader

Creates a klinecharts DataLoader from a Datafeed instance.

function createDataLoader(
  datafeed: Datafeed,
  dispatch: Dispatch<KlinechartsUIAction>,
): DataLoader;

This bridges the Datafeed interface to the klinecharts native DataLoader format.

Behavior:

| klinecharts request type | Action | | ------------------------ | ------------------------------------------------------------------------------------------------------- | | "init" | Loads the latest ~1000 bars (to=Date.now(), from=0), saves oldestTimestamp, increments currentGen | | "forward" | Loads bars older than oldestTimestamp - 1 for left-scroll pagination | | "backward" | Ignored (real-time handled via subscribeBar) |

Race condition protection: each "init" increments currentGen. If a "forward" request completes after a new "init" has started, the result is discarded.

function ChartView() {
  const { state, dispatch, datafeed } = useKlinechartsUI();

  const dataLoader = useMemo(
    () => createDataLoader(datafeed, dispatch),
    [datafeed, dispatch],
  );

  return (
    <KLineChart
      dataLoader={dataLoader}
      symbol={state.symbol ?? undefined}
      period={state.period}
      locale={state.locale}
      timezone={state.timezone}
      styles={state.theme}
      onReady={(chart) => dispatch({ type: "SET_CHART", chart })}
    />
  );
}

TA (Technical Analysis)

A standalone math library for computing common technical indicators. Used internally by indicator templates and available to custom scripts via useScriptEditor.

import { TA } from "react-klinecharts-ui";

| Function | Signature | Returns | |----------|-----------|---------| | TA.sma | (data: number[], period: number) | number[] — Simple Moving Average | | TA.ema | (data: number[], period: number) | number[] — Exponential Moving Average | | TA.rma | (data: number[], period: number) | number[] — Running (Wilder's) Moving Average | | TA.wma | (data: number[], period: number) | number[] — Weighted Moving Average | | TA.hma | (data: number[], period: number) | number[] — Hull Moving Average | | TA.stdev | (data: number[], period: number) | number[] — Standard Deviation | | TA.rsi | (data: number[], period: number) | (number \| null)[] — Relative Strength Index | | TA.macd | (data: number[], fast?: number, slow?: number, signal?: number) | { dif, dea, macd } — each (number \| null)[] | | TA.bollinger | (data: number[], period?: number, mult?: number) | { upper, mid, lower } — each (number \| null)[] | | TA.tr | (highs: number[], lows: number[], closes: number[]) | number[] — True Range | | TA.atr | (highs: number[], lows: number[], closes: number[], period: number) | number[] — Average True Range | | TA.vwap | (highs: number[], lows: number[], closes: number[], volumes: number[]) | number[] — Volume Weighted Average Price | | TA.cci | (highs: number[], lows: number[], closes: number[], period: number) | number[] — Commodity Channel Index | | TA.stoch | (highs: number[], lows: number[], closes: number[], kPeriod?, kSmooth?, dPeriod?) | { k, d } — each (number \| null)[] |

Data & Constants

All constants are exported from the root index.ts:

DEFAULT_PERIODS

const DEFAULT_PERIODS: TerminalPeriod[] = [
  { span: 1, type: "minute", label: "1m" },
  { span: 5, type: "minute", label: "5m" },
  { span: 15, type: "minute", label: "15m" },
  { span: 1, type: "hour", label: "1H" },
  { span: 2, type: "hour", label: "2H" },
  { span: 4, type: "hour", label: "4H" },
  { span: 1, type: "day", label: "D" },
  { span: 1, type: "week", label: "W" },
  { span: 1, type: "month", label: "M" },
  { span: 1, type: "year", label: "Y" },
];

TIMEZONES

Array of TimezoneOption[] — 18 timezones. Fields: key (IANA) and localeKey (short name).

MAIN_INDICATORS / SUB_INDICATORS

String arrays of indicator names used as the available-for-selection list.

INDICATOR_PARAMS

const INDICATOR_PARAMS: Record<string, IndicatorDefinition>;

interface IndicatorDefinition {
  name: string;
  localeKey: string;
  params: { label: string; defaultValue: number }[];
}

Used internally by getIndicatorParams inside useIndicators.

DRAWING_CATEGORIES

Array of drawing tool categories. Used by useDrawingTools.

CANDLE_TYPES

const CANDLE_TYPES: CandleTypeOption[] = [
  { key: "candle_solid", localeKey: "candle_solid" },
  { key: "candle_stroke", localeKey: "candle_stroke" },
  { key: "candle_up_stroke", localeKey: "candle_up_stroke" },
  { key: "candle_down_stroke", localeKey: "candle_down_stroke" },
  { key: "ohlc", localeKey: "ohlc" },
  { key: "area", localeKey: "area" },
];

PRICE_AXIS_TYPES

const PRICE_AXIS_TYPES = ["normal", "percentage", "log"] as const;
type PriceAxisType = "normal" | "percentage" | "log";

Custom Indicator Templates

11 TradingView-style indicator templates ported from QUANTIX Extended Edition. All are registered automatically via registerExtensions. Each template uses the TA library for calculations and includes custom draw functions for TradingView-like visual styling (gradient fills, dashed level lines, multi-color histograms).

import { indicators } from "react-klinecharts-ui";
// indicators === [bollTv, cci, hma, ichimoku, maRibbon, macdTv, pivotPoints, rsiTv, stochastic, superTrend, vwap]

Main chart indicators

| Template | Name | Default params | Description | |----------|------|----------------|-------------| | bollTv | BOLL_TV | [20, 2] | Bollinger Bands — TradingView style with filled band area, SMA midline, and upper/lower bands | | hma | HMA | [9] | Hull Moving Average — high smoothing with minimal lag via TA.hma() | | ichimoku | ICHIMOKU | [9, 26, 52, 26] | Ichimoku Cloud — Tenkan-sen, Kijun-sen, Senkou Span A/B (filled cloud), Chikou Span | | maRibbon | MA_RIBBON | [5, 10, 20, 30, 50, 100] | Moving Average Ribbon — 6 EMAs with distinct colors for trend visualization | | pivotPoints | PIVOT_POINTS | [1] | Standard pivot with Pivot, R1, R2, S1, S2 levels as dashed horizontal lines | | superTrend | SUPERTREND | [10, 3] | ATR-based trend — dynamic green (up) / red (down) line coloring | | vwap | VWAP | [] | Volume Weighted Average Price — single blue line via TA.vwap() |

Sub-pane indicators

| Template | Name | Default params | Description | |----------|------|----------------|-------------| | macdTv | MACD_TV | [12, 26, 9] | 4-color histogram: growing-positive (#26A69A), shrinking-positive (#B2DFDB), growing-negative (#FFCDD2), shrinking-negative (#EF5350). MACD line (#2962FF), Signal line (#FF6D00) | | rsiTv | RSI_TV | [14, 14] | RSI + MA line. Dashed levels at 70/50/30. Gradient fills in overbought (>70, red) and oversold (<30, green) zones | | cci | CCI | [20] | Commodity Channel Index via TA.cci() with dashed +100/0/-100 reference lines | | stochastic | STOCHASTIC | [14, 1, 3] | %K (#2962FF) and %D (#FF6D00) lines. Dashed 80/50/20 levels. Gradient fills in overbought/oversold zones |

Drawing Overlays

OverlayTemplate instances for drawing tools. Automatically registered when registerExtensions: true (default).

Named exports:

| Export | Overlay name | Description | | ----------------------------- | ------------------------------- | ------------------- | | arrow | "arrow" | Arrow | | circle | "circle" | Circle | | rect | "rect" | Rectangle | | triangle | "triangle" | Triangle | | parallelogram | "parallelogram" | Parallelogram | | fibonacciCircle | "fibonacciCircle" | Fibonacci circle | | fibonacciSegment | "fibonacciSegment" | Fibonacci segment | | fibonacciSpiral | "fibonacciSpiral" | Fibonacci spiral | | fibonacciSpeedResistanceFan | "fibonacciSpeedResistanceFan" | Fibonacci fan | | fibonacciExtension | "fibonacciExtension" | Fibonacci extension | | gannBox | "gannBox" | Gann box | | threeWaves | "threeWaves" | 3-wave pattern | | fiveWaves | "fiveWaves" | 5-wave pattern | | eightWaves | "eightWaves" | 8-wave pattern | | anyWaves | "anyWaves" | Custom wave pattern | | abcd | "abcd" | ABCD pattern | | xabcd | "xabcd" | XABCD pattern | | elliottWave | "elliottWave" | Elliott Wave (5-wave cycle with numbered vertices) | | gannFan | "gannFan" | Gann Fan (1x1, 1x2, etc.) | | fibRetracement | "fibRetracement" | Fibonacci retracement levels | | parallelChannel | "parallelChannel" | Parallel channel (two parallel lines) | | longPosition | "longPosition" | Long position risk/reward (TP/SL with % labels) | | shortPosition | "shortPosition" | Short position risk/reward (TP/SL with % labels) | | measure | "measure" | Measure tool (price %, bar count, time delta) | | brush | "brush" | Freehand brush drawing (Bezier smoothing) | | ray | "ray" | Infinite ray from a point |

Extensions

registerExtensions

Registers all built-in drawing overlays via registerOverlay. Called automatically by the provider when registerExtensions: true.

import { registerExtensions } from "react-klinecharts-ui";
registerExtensions(); // Idempotent — repeated calls are ignored

orderLine

Overlay template for horizontal price level lines. Not registered automatically — must be passed explicitly to the provider.

import { orderLine, KlinechartsUIProvider } from "react-klinecharts-ui";

<KlinechartsUIProvider overlays={[orderLine]}>...</KlinechartsUIProvider>;

Implementation details:

needDefaultYAxisFigure: false — custom rendering of the Y-axis mark
createYAxisFigures — draws a colored price mark on the right axis
createPointFigures — draws a horizontal line with an optional text label
performEventPressedMove — updates points[0].value during drag
Uses chart.getSymbol()?.pricePrecision ?? 2 for price formatting

OrderLineExtendData

All fields are optional. Defaults produce an orange dashed line with a white-on-orange price mark.

interface OrderLineExtendData {
  /** Primary color for line, mark bg, and label fallback. Default: "rgba(255, 165, 0, 0.85)" */
  color?: string;
  /** Optional text label displayed above the line. */
  text?: string;
  /** Line style overrides. */
  line?: OrderLineLineStyle;
  /** Y-axis price mark style overrides. */
  mark?: OrderLineMarkStyle;
  /** Text label style overrides. */
  label?: OrderLineLabelStyle;
}

interface OrderLineLineStyle {
  style?: "solid" | "dashed" | "dotted"; // Default: "dashed"
  width?: number; // Default: 1
  dashedValue?: [number, number]; // Default: [4, 2]
}

interface OrderLineMarkStyle {
  color?: string; // Text color. Default: "#ffffff"
  bg?: string; // Background (falls back to top-level color)
  borderRadius?: number; // Default: 2
  font?: OrderLineFontStyle;
  padding?: OrderLinePadding;
}

interface OrderLineLabelStyle {
  color?: string; // Text color (falls back to top-level color)
  bg?: string; // Background. Default: "transparent"
  borderRadius?: number; // Default: 0
  font?: OrderLineFontStyle;
  padding?: OrderLinePadding;
  offset?: OrderLinePadding; // Position offset. Defaults: x=8, y=3
}

interface OrderLineFontStyle {
  size?: number; // Default: 11
  family?: string; // Default: "Helvetica Neue, Arial, sans-serif"
  weight?: string; // Default: "bold" (mark) / "normal" (label)
}

interface OrderLinePadding {
  x?: number;
  y?: number;
}

All sub-interfaces (OrderLineLineStyle, OrderLineMarkStyle, OrderLineLabelStyle, OrderLineFontStyle, OrderLinePadding) are exported as named types from both the main and extensions entry points.

depthOverlay

Overlay template for visualizing order book depth as horizontal liquidity bars at each price level. Shows cumulative buy/sell volume at price levels, useful for understanding support/resistance zones.

import { depthOverlay, KlinechartsUIProvider } from "react-klinecharts-ui/extensions";

<KlinechartsUIProvider overlays={[depthOverlay]}>...</KlinechartsUIProvider>;