Configuration

Exports

Name	Kind	Description
NewsWidget	Component	Economic calendar analysis overlay for your chart
NewsWidgetProps	Type	Props for NewsWidget
SymbolMapper	Type	Mapping from iC Candle tickers to your broker’s symbol names
ICCANDLE_TICKERS	Type	Union of all iC Candle ticker strings (keys of SymbolMapper)

NewsWidget props

Prop	Type	Required	Description
chartWidget	IChartingLibraryWidget | null	Yes	Live TradingView widget instance.
children	ReactNode	Yes	Your chart UI.
widgetKey	string	Yes	iC Candle API key (theme, chart data, news events, validation).
defaultSymbol	string	Yes	Default symbol (e.g. XAU_USD, EURUSD). Fallback when symbol is unrecognized or unmapped.
symbolMapper	SymbolMapper	No	Maps iC Candle tickers to your TradingView symbol names.
chartInterval	"1" | "5" | "15" | "30" | "60"	Yes	Initial candle interval in minutes.
theme	"light" | "dark" | "system"	No	Resolved theme tokens and chart overlays.

Widget key and remote theming

On mount:

• URL: https://api.iccandle.ai/corporate-client/v1/widgetStyle/search/user/?service_type=search
• Header: api-key: <widgetKey>

CSS custom properties (--iccandle-primary, --iccandle-border, --iccandle-background, --iccandle-text, etc.) are applied on the widget root for light/dark branding.

Theme prop vs. API tokens: The theme prop ("light" | "dark" | "system") chooses which variant of those tokens to apply.

Behavior summary

• Subscribes to chart readiness, resolution, symbol changes, and drawing events.
• Displays economic calendar events as interactive timescale marks.
• On event selection: split layout with detail panel and pip-range visualization.
• Draws pip-range rectangles, trend lines, and pip annotations on the chart.
• Fetches similar historical events; shows metadata (actual, forecast, previous).
• Configurable candle windows (10–50 candles).
• Stores selected events in localStorage (iccandle:current-news-event) for timescale mark sync.
• Listens for window message events for chart/news integration.

Chart switching between TradingView and iC Candle

Scenario	Chart shown
Older event (~50+ candles after event on selected timeframe)	iC Candle history chart via iframe (curated pip-range analysis).
Recent / upcoming event (timeframe not fully elapsed)	TradingView in split layout with pip-range overlays on the left; iC Candle iframe on the right.

Symbol handling and limitations

iC Candle’s history chart supports a fixed set of symbols. For currency events, only symbols related to that currency are available in the iC Candle chart.

On TradingView, symbol filtering cannot be controlled by the widget - pip-range overlays apply to the currently active symbol, which may not match the event’s currency.

Symbol name mapping (symbolMapper)

iC Candle and your broker often use different symbol names. Map iC Candle tickers to your chart symbols:

<NewsWidget
  chartWidget={chartWidget}
  widgetKey="your-api-key"
  defaultSymbol="XAUUSD"
  chartInterval="15"
  theme="dark"
  symbolMapper={{
    XAUUSD: "GOLD",
    USDCAD: "USD_CAD",
    EURUSD: "EURUSD",
  }}
>
  {children}
</NewsWidget>

When the iC Candle iframe sends a symbol change, the widget looks up symbolMapper; if missing, it falls back to defaultSymbol.

Optional: timescale marks (news/events)

If your data feed implements getTimescaleMarks, sync from localStorage key iccandle:current-news-event:

getTimescaleMarks: async (
  symbolInfo: LibrarySymbolInfo,
  from: number,
  to: number,
  onResult: GetMarksCallback<TimescaleMark>,
) => {
  const marks: TimescaleMark[] = [];

  try {
    const currentNewsEvent = JSON.parse(
      localStorage.getItem("iccandle:current-news-event") || "{}",
    ) as NewsEventType;

    const { id, timestamp, event_name, currency, forecast, previous, actual } =
      currentNewsEvent;

    if (!id || !Number.isFinite(timestamp) || timestamp <= 0) return;
    const hasAlready = marks.some((m) => String(m.id) === String(id));
    if (hasAlready) return;

    marks.push({
      id: id,
      time: timestamp / 1000,
      color: "green",
      label: event_name.slice(0, 1),
      tooltip: [
        event_name,
        `Current Forecast: ${forecast || "-"}`,
        `Previous Forecast: ${previous || "-"}`,
        `Previous Actual: ${actual || "-"}`,
      ],
      ...(currency ? { imageUrl: `/images/symbols/${currency}.svg` } : {}),
    });
  } catch {
    // no-op
  }
  onResult(marks);
},

License

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