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)

Wraps subscribeBars so iC Candle can push replay bars and optionally block live ticks during playback.

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

datafeed: withPlayChart(myDatafeed),
// or factory + args:
datafeed: withPlayChart(createDatafeed, arg1, arg2),

getCustomIndicators(theme?)

Returns a Promise of TradingView CustomIndicator[] used for generated / predicted candle overlays. Pass "light" or "dark" to match chart theme. Wire it into widget options:

custom_indicators_getter: () => getCustomIndicators("light"),

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.