widget-iccandle

React component that wraps an existing TradingView Charting Library widget and adds ICCandle’s scanner UI: a draggable popup to run pattern search over a user-selected bar range, with theming loaded from ICCandle’s API.

Published as ESM and CommonJS; component styles are bundled and injected at runtime (no separate CSS import).

Install

npm install widget-iccandle

Peer dependencies: react and react-dom ≥ 18.

You must obtain the TradingView Charting Library under your own license and load it in your app. This package does not ship the charting library assets.

Quick start

import { useState } from "react";
import type { IChartingLibraryWidget } from "charting_library/charting_library";
import { SelectorWidget } from "widget-iccandle";

function App() {
  const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
    null,
  );
  const widgetKey = "icc_search_..."; // ICCandle-issued key (48 hex chars after prefix)

  return (
    <SelectorWidget
      chartWidget={chartWidget}
      widgetKey={widgetKey}
      theme="system"
      submitCallback={(iframeSrc) => {
        // Full URL for the ICCandle plugin iframe (open in modal, new window, etc.)
        console.log(iframeSrc);
      }}
    >
      {/* Your chart container + TradingView bootstrap; call setChartWidget when ready */}
      <div id="tv_chart_container" style={{ height: "100%" }} />
    </SelectorWidget>
  );
}

Replace the chart placeholder with your TradingView initialization and pass the IChartingLibraryWidget instance when onChartReady (or equivalent) fires.

API

Exports

| Name | Kind | Description | | -------------------- | ------ | -------------------------------------------- | | SelectorWidget | Component | Scanner overlay around your chart subtree | | SelectorWidgetProps| Type | Props for SelectorWidget |

SelectorWidget props

| Prop | Type | Required | Description | | ----------------- | --------------------------------------- | -------- | ----------- | | chartWidget | IChartingLibraryWidget \| null | Yes | Live TradingView widget instance (null until ready). | | children | ReactNode | Yes | Your chart UI (e.g. container + library bootstrap). | | widgetKey | string | Yes | ICCandle API key (icc_search_ + 48 hex chars). Used for theme fetch, candle cache, and scanner validation. | | submitCallback | (iframeSrc: string) => void | Yes | Called after a successful scan setup with the plugin iframe URL (query string includes window size, timestamps, symbol, candle_id, apiKey, theme, optional filters). | | theme | "light" \| "dark" \| "system" | No | Defaults to sensible behavior; "system" follows prefers-color-scheme. Affects resolved theme tokens and the plugin URL. |

Widget key and remote theming

On mount, the component loads branding colors from ICCandle:

• 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, etc.) are applied on the widget root so the scanner matches your configured light/dark tokens.

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; window size and exported candles drive the scanner.
• Posts candles to ICCandle’s cache endpoint before opening the plugin URL (see scanner implementation for details).
• Listens for window message events for chart/news integration and can clear persisted news mark selections (localStorage key tv:selected-news-events) when starting a scan.

Optional: timescale marks (news/events)

If your data feed implements getTimescaleMarks, you can surface stored events (e.g. from localStorage under tv:selected-news-events) as marks on the time axis. Example shape:

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

    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.

Development (this repo)

| Script | Command | Purpose | | ------------- | ------------ | ------- | | Dev demo | npm run dev | Vite app with local charting library (see vite.config.ts). | | Library build | npm run build | Emits dist/ (JS, CJS, bundled CSS injection, declarations). | | Lint | npm run lint | ESLint. |

prepublishOnly runs build before publish.

License

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