Get started

Step 1 - Install the package

npm install @iccandle/news

Ensure react and react-dom are installed and meet the peer version range.

Step 2 - Host the Charting Library

Copy the TradingView Charting Library build into a path your app can serve as static files (e.g. public/charting_library/ in Vite or Create React App).

Import the library constructor from that path in your bundler setup. The library is not bundled inside @iccandle/news; it loads at runtime via library_path on the widget options.

Step 3 - Bootstrap TradingView and capture the widget instance

import { useEffect, useRef, useState } from "react";
import type {
  ChartingLibraryWidgetOptions,
  IChartingLibraryWidget,
  ResolutionString,
} from "charting_library/charting_library";
import { widget } from "charting_library/charting_library";

const LIBRARY_PATH = "/charting_library/";

const containerRef = useRef<HTMLDivElement>(null);
const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
  null,
);

useEffect(
  () => {
    const el = containerRef.current;
    if (!el) return;

    const options: ChartingLibraryWidgetOptions = {
      container: el,
      library_path: LIBRARY_PATH,
      symbol: "XAU_USD",
      interval: "15" as ResolutionString,
      datafeed: yourDatafeed,
      locale: "en",
      autosize: true,
    };

    const tv = new widget(options);
    setChartWidget(tv);

    return () => {
      try {
        tv.remove();
      } catch {
        /* no-op */
      }
      setChartWidget(null);
    };
  },
  [
    /* inputs that should recreate the chart */
  ],
);

If your integration only exposes the instance after onChartReady, call setChartWidget inside that callback.

Step 4 - Wrap the chart with NewsWidget

NewsWidget must wrap the same subtree that contains the chart container:

import { NewsWidget } from "@iccandle/news-widget";

const widgetKey = "your-iccandle-api-key";

<NewsWidget
  chartWidget={chartWidget}
  widgetKey={widgetKey}
  defaultSymbol="XAU_USD"
  chartInterval="15"
  theme="dark"
>
  <div ref={containerRef} style={{ height: "100%", minHeight: 400 }} />
</NewsWidget>;

When a news event is selected, the widget switches to a 50/50 split layout: event detail card and TradingView chart (with pip-range overlays) on the left, and the iC Candle iframe on the right. On mobile (<1024px) the panels stack vertically.

Step 5 - Interact with news events

Once mounted:

• Economic calendar events appear as timescale marks on the chart’s time axis.
• Clicking an event opens the detail panel (actual, forecast, previous, impact status, similar historical events).
• Pip-range visualization draws on the chart: green rectangles (upside), red rectangles (downside), dotted trend lines, pip annotations at extremes.
• Candle window is configurable (10–50 candles) for how far after the event range analysis extends.

TypeScript: import NewsWidgetProps for explicit prop typing. Import IChartingLibraryWidget from your Charting Library typings path.

Theme and remote branding

• theme="light" / theme="dark" / theme="system" - affects widget chrome and chart overlays; "system" uses prefers-color-scheme.
• On mount, branding tokens are fetched and applied as CSS custom properties (--iccandle-primary, --iccandle-border, --iccandle-background, --iccandle-text, etc.).

Full working example

import { useEffect, useRef, useState } from "react";
import type {
  ChartingLibraryWidgetOptions,
  IChartingLibraryWidget,
  ResolutionString,
} from "charting_library/charting_library";
import { widget } from "charting_library/charting_library";
import { NewsWidget } from "@iccandle/news-widget";

const LIBRARY_PATH = "/charting_library/";
const WIDGET_KEY = "your-iccandle-api-key";

export function ChartWithNewsWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
    null,
  );

  useEffect(() => {
    const el = containerRef.current;
    if (!el) return;

    const options: ChartingLibraryWidgetOptions = {
      container: el,
      library_path: LIBRARY_PATH,
      symbol: "XAU_USD",
      interval: "15" as ResolutionString,
      datafeed: yourDatafeed,
      locale: "en",
      autosize: true,
      fullscreen: false,
    };

    const tv = new widget(options);
    setChartWidget(tv);

    return () => {
      try {
        tv.remove();
      } catch {
        /* no-op */
      }
      setChartWidget(null);
    };
  }, []);

  return (
    <div style={{ height: 600, width: "100%" }}>
      <NewsWidget
        chartWidget={chartWidget}
        widgetKey={WIDGET_KEY}
        defaultSymbol="XAU_USD"
        chartInterval="15"
        theme="dark"
      >
        <div ref={containerRef} style={{ height: "100%", width: "100%" }} />
      </NewsWidget>
    </div>
  );
}

See src/tradingview/TradingviewChart.tsx in the widget-news dev app for a full reference.

Common patterns

Pattern	Approach
Full-page chart	Parent height: 100vh, autosize: true on the TradingView widget.
Dashboard embed	Fixed height (e.g. 600px); NewsWidget handles split layout internally.
News / events on the time axis	Datafeed getTimescaleMarks + localStorage - see Optional: timescale marks.