Configuration

Exports

Name	Kind	Description
WidgetIccandle	Component	Chart overlay + results iframe
WidgetIccandleProps	Type	Props for WidgetIccandle
WidgetIccandleChartRefs	Type	Refs for highlight bars / generated-candle studies
WidgetLanguage	Type	Supported locale codes
withPlayChart	Function	Wraps a TradingView datafeed for replay bar injection
getCustomIndicators	Function	Returns iC Candle custom indicators (generated candles)
getGeneratedCandlesMaskColor	Function	Theme-aware mask color for generated candles

WidgetIccandle props

Prop	Type	Required	Description
chartWidget	IChartingLibraryWidget | null	Yes	Live TradingView widget (null until ready).
children	ReactNode | ((chartRefs) => ReactNode)	Yes	Chart UI, or render prop receiving WidgetIccandleChartRefs.
theme	"light" | "dark" | "system"	No	Scanner chrome + iframe theme. "system" follows prefers-color-scheme.
language	WidgetLanguage	No	UI + iframe locale. One of: en, zh, vi, th, ko, ja, mn, ru. Defaults to en.
onCloseResult	() => void	No	Called when the embed posts close-result.
iframeLoaded	boolean	No	When false, disables scan / track actions until the results iframe is ready. Defaults to enabled behavior in the scanner.

IChartingLibraryWidget must be imported from your Charting Library typings — this package does not re-export TradingView types.

WidgetIccandleChartRefs

Field	Description
highlightBarsRef	Bars used for highlight / selection overlays
generatedCandlesBackgroundStudyIdRef	Study id for the generated-candles background indicator
generatedCandlesStudyIdRef	Study id for the generated-candles indicator

withPlayChart(datafeed)

Required for chart replay / predict. Wraps your TradingView datafeed’s subscribeBars so the widget can:

1. Inject replay bars into the live tick stream when the embed posts play-chart or replay.
2. Block live ticks while playback is active, so real-time updates do not overwrite predicted candles.

Signature

withPlayChart(datafeed: IBasicDataFeed): IBasicDataFeed

Argument	Type	Description
datafeed	IBasicDataFeed	Ready datafeed instance (must expose onReady).

Usage

import { withPlayChart } from "@iccandle/reactjs-widget";

datafeed: withPlayChart(myDatafeed),

Notes

• The returned object is still a normal datafeed; only subscribeBars is wrapped.
• Pair with getCustomIndicators — without both, replay / predict overlays will not work.

getCustomIndicators(theme?)

Registers iC Candle’s custom studies used to draw generated / predicted candles on top of the main series. Returns a Promise of TradingView CustomIndicator[] for custom_indicators_getter.

Signature

getCustomIndicators(theme?: "light" | "dark"): Promise<readonly CustomIndicator[]>

Argument	Type	Default	Description
theme	"light" | "dark"	"light"	Pane mask color so predicted bars hide the underlying series. Must match the chart theme.

Studies returned

Study name	Role
Generated Candles Background - By iC Candle	Hidden mask layer that paints over real bars at predicted timestamps.
Generated Candles - By iC Candle	Visible OHLC overlay (bullish #00dfb9 / bearish #ffb84d) for predicted candles.

WidgetIccandle creates and drives these studies via chartRefs (generatedCandlesBackgroundStudyIdRef, generatedCandlesStudyIdRef) when the embed sends replay / predict data.

Usage

import { getCustomIndicators } from "@iccandle/reactjs-widget";

const options: ChartingLibraryWidgetOptions = {
  // ...
  datafeed: withPlayChart(yourDatafeed),
  custom_indicators_getter: () => getCustomIndicators("light"),
};

Keep getCustomIndicators(theme) in sync with the chart widget theme (and preferably with WidgetIccandle’s theme prop). Use getGeneratedCandlesMaskColor(theme) if you need the same mask color elsewhere (#ffffff light / #131722 dark).

Together with withPlayChart

Helper	Job
withPlayChart	Lets the widget push bars into the datafeed and mute live ticks during playback.
getCustomIndicators	Draws the predicted candle visuals (mask + colored OHLC) as custom studies.

Both are required for replay / predict from the results iframe.

Auth and storage

Key	Purpose
iccandle_token	Bearer token for scan cache, pattern tracker, and related APIs. Set by the embed via sign-in-success.
search-filter	Scanner advanced options (symbols, top_k, period, probability).
tv:selected-news-events	JSON array of news events used as timescale marks.
tv:clicked-news-event	Last clicked calendar event for mark highlighting.
tv:latest-symbol	Last chart symbol (used by the demo app / fallbacks).

postMessage bridge

Messages are accepted only from the results origin (https://embed-iccandle-app.iccandle.ai).

Direction	Type / action	Effect
Embed → parent	play-chart	Inject / clear replay candles on the chart
Embed → parent	loading	Toggle scanner loading UI
Embed → parent	sign-in-success	Persist iccandle_token from payload.id_token
Embed → parent	close-result	Clears play state; calls onCloseResult
Embed → parent	pattern_selected / custom_pattern_selected	Draw date range for the compared pattern
Embed → parent	clear_pattern_selected / clear_custom_pattern_selected	Remove pattern date range
Embed → parent	eventClicked	Center chart, draw event line, show mark
Embed → parent	replay	Start / stop event replay candles
Embed → parent	back / back-to-similar-events	Clear event line / replay
Embed → parent	nav-click	Hide scanner on /news; restore otherwise
Parent → embed	parent-origin	Host origin for Stripe return
Parent → embed	payment-success	Refresh subscription after checkout

Optional: timescale marks (news/events)

If your datafeed implements getTimescaleMarks, surface stored events as marks:

getTimescaleMarks: async (
  symbolInfo,
  from,
  to,
  onResult,
) => {
  const marks = [];
  try {
    const allNewsEvents = JSON.parse(
      localStorage.getItem("tv:selected-news-events") || "[]",
    );

    allNewsEvents?.forEach(({ id, timestamp, event_name, currency }) => {
      if (!id || !Number.isFinite(timestamp) || timestamp <= 0) return;
      if (marks.some((m) => String(m.id) === String(id))) return;

      marks.push({
        id,
        time: timestamp / 1000,
        color: "green",
        label: event_name.slice(0, 1) || "N",
        tooltip: [event_name],
        ...(currency ? { imageUrl: `/images/symbols/${currency}.svg` } : {}),
        showLabelWhenImageLoaded: true,
      });
    });
  } catch {
    /* ignore */
  }
  onResult(marks);
};

Adjust paths and types to match your app and TradingView typings.

Theming

Scanner UI uses CSS variables on .iccandle-selector-widget:

• --iccandle-primary
• --iccandle-primary-gradient-end
• --iccandle-background
• --iccandle-border
• --iccandle-text
• --iccandle-secondary
• --iccandle-font

Light and dark defaults live in the bundled stylesheet. The theme prop toggles the .iccandle-dark class and is forwarded to the iframe.

Behavior summary

• Subscribes to chart readiness, resolution, symbol changes, and drawing events.
• Manages a date_range multipoint drawing so the user can adjust the bar window (default: 25 bars).
• Posts candles to https://scan-service.iccandle.ai/cacheCandle, then navigates the results iframe with query params (ws, tk, et, symbol, tf, cid, filters, theme).
• Hosts the results iframe at https://embed-iccandle-app.iccandle.ai and syncs via postMessage.

License

MIT. TradingView Charting Library is subject to its own license from TradingView.