@cryhub/chart-widget

A professional, embeddable kline (candlestick) chart widget for crypto trading platforms, powered by the CryHub market data API.

• Real-time WebSocket price feeds
• 9 timeframes, 5 chart types
• 68 drawing tools with undo/redo
• 36 built-in indicators (overlay + sub-pane)
• Full RTL support (locale: 'fa')
• Dark & light themes with full color override
• Zero peer dependencies — single self-contained bundle
• Three output targets: ES module · IIFE script tag · Web Component

Table of Contents

1. Quick Start
2. Installation
3. Usage
4. Options Reference
5. Chart Types
6. Timeframes
7. Indicators
8. Drawing Tools
9. Theming & Colors
10. Internationalization
11. Multi-Instance Support
12. Development
13. Building
14. Docker

Quick Start

Script Tag (IIFE)

<div id="chart" style="width: 100%; height: 600px;"></div>

<script src="dist/cryhub-chart.iife.js"></script>
<script>
  CryHubChart.createCryHubChart(document.getElementById('chart'), {
    token: 'YOUR_API_TOKEN',
    symbol: 'btcusdt',
    currencies: ['usdt'],
    defaultCurrency: 'usdt',
    timeframes: ['1m', '5m', '15m', '30m', '1h', '4h', '1d'],
    defaultTimeframe: '15m',
    theme: 'dark',
    locale: 'en',
  });
</script>

Web Component

<cryhub-chart id="chart" style="width: 100%; height: 600px;"></cryhub-chart>

<script type="module" src="dist/cryhub-chart.es.js"></script>
<script type="module">
  const el = document.getElementById('chart');
  el.options = {
    token: 'YOUR_API_TOKEN',
    symbol: 'btcusdt',
    currencies: ['usdt'],
    defaultCurrency: 'usdt',
    timeframes: ['15m', '1h', '4h', '1d'],
    defaultTimeframe: '15m',
    theme: 'dark',
    locale: 'en',
  };
</script>

ES Module (NPM)

import { createCryHubChart } from '@cryhub/chart-widget';

createCryHubChart(document.getElementById('chart'), {
  token: process.env.CRYHUB_TOKEN,
  symbol: 'btcusdt',
  currencies: ['usdt', 'tmn'],
  defaultCurrency: 'usdt',
  timeframes: ['1m', '5m', '15m', '30m', '1h', '4h', '1d'],
  defaultTimeframe: '15m',
  theme: 'dark',
  locale: 'en',
});

Installation

npm install @cryhub/chart-widget

Or use directly from dist/ without a build step via the IIFE bundle.

Usage

createCryHubChart(element, options)

| Param | Type | Description | |---|---|---| | element | HTMLElement | Container element. The widget fills it completely. | | options | CryHubChartOptions | Configuration object (see Options Reference). |

Returns the <cryhub-chart> element. You can update options at any time:

const chart = createCryHubChart(el, options);

// Update options live — only changed fields take effect
chart.options = { ...chart.options, theme: 'light' };

Options Reference

Authentication

| Option | Type | Required | Description | |---|---|---|---| | token | string | ✅ | CryHub REST API token. Sent as Authorization: Bearer <token>. | | wsToken | string | — | Separate token for WebSocket. Falls back to token if omitted. |

Market Data

| Option | Type | Default | Description | |---|---|---|---| | symbol | string | required | Lowercase CryHub pair, e.g. 'btcusdt'. Auto-formats to BTC/USDT in the top bar. | | symbolLabel | string | — | Display name override (e.g. 'BTC/TMN'). Overrides the auto-format. | | currencies | QuoteCurrency[] | required | Quote currencies to offer. At least one required. Options: 'usdt' 'tmn' 'aed' 'eur'. | | defaultCurrency | QuoteCurrency | required | Active currency on load. Must be in currencies. | | timeframes | Timeframe[] | required | Timeframes to show in the top bar. At least one required. | | defaultTimeframe | Timeframe | required | Active timeframe on load. Must be in timeframes. |

Branding

| Option | Type | Description | |---|---|---| | brandName | string | Company name shown top-left. | | brandLogo | string | URL to logo image. Displayed at 24px height. Falls back to brandName on load error. |

Appearance

| Option | Type | Default | Description | |---|---|---|---| | theme | 'dark' \| 'light' | 'dark' | Base color palette. Set by the company — not changeable by end users. | | locale | 'en' \| 'fa' | 'en' | Layout direction. 'fa' mirrors the entire UI to RTL (Persian layout). | | colors | DeepPartial<ColorScheme> | — | Brand color overrides applied on top of the base theme. See Theming. |

Feature Access Controls

These control what end users can see and interact with. They do not affect company-level config.

| Option | Type | Default | Description | |---|---|---|---| | allowChartSettings | boolean | true | Show the ⚙ settings button in the top bar. | | showDrawingTools | boolean | true | Show the drawing toolbar. | | showIndicators | boolean | true | Show the Indicators button in the top bar. | | showVolumeProfile | boolean | true | Show the volume sub-pane. | | showFullscreen | boolean | true | Show the fullscreen expand button. | | showScreenshot | boolean | true | Show the screenshot/download button. | | showChartTypeSelector | boolean | true | Show the chart type selector in the top bar. |

Restrictions

| Option | Type | Default | Description | |---|---|---|---| | allowedChartTypes | ChartType[] | all 5 | Restrict which chart types appear in the selector. | | allowedDrawingTools | DrawingToolId[] \| 'all' | 'all' | Restrict which drawing tools are available. Use tool IDs (e.g. ['trendline', 'hline', 'rectangle']). | | allowedIndicators | IndicatorId[] \| 'all' | 'all' | Restrict which indicators appear in the add-indicator modal (e.g. ['ema', 'rsi', 'macd', 'bb']). |

Default Indicators

| Option | Type | Default | Description | |---|---|---|---| | defaultIndicators | IndicatorConfig[] | EMA 20/50/100/200 | Indicators pre-loaded on init. Pass [] to disable all defaults. | | lockDefaultIndicators | boolean | true | When true, end users can configure but not remove default indicators. |

Built-in EMA defaults (used when defaultIndicators is omitted):

| Indicator | Color | |---|---| | EMA(20) | #26c6da (cyan) | | EMA(50) | #f59e0b (amber) | | EMA(100) | #e040fb (purple) | | EMA(200) | #4ade80 (green) |

Custom defaults example:

defaultIndicators: [
  { id: 'sma', params: { length: 7,  color: '#e74c3c' } },
  { id: 'sma', params: { length: 25, color: '#3498db' } },
  { id: 'sma', params: { length: 99, color: '#2ecc71' } },
],
lockDefaultIndicators: true,

Viewport

| Option | Type | Default | Description | |---|---|---|---| | defaultBarSpacing | number | — | Initial bar width in pixels (2–40). Takes priority over defaultVisibleBars when set. | | defaultVisibleBars | number | 75 | Number of candles visible on first load. Ignored when defaultBarSpacing is set. | | maxSubPanes | number | 3 | Maximum sub-indicator panes below the main chart. Volume pane does not count. | | height | number \| string | '100%' | Widget height. Number = px, string = any CSS value ('600px', '80vh'). | | width | number \| string | '100%' | Widget width. | | storageKey | string | cryhub-chart-{symbol} | localStorage namespace for user preferences (drawings, indicators, settings). |

Chart Types

| ID | Display name | |---|---| | 'candlestick' | Candlestick | | 'heikin-ashi' | Heikin-Ashi | | 'bar' | Bar (OHLC) | | 'line' | Line | | 'area' | Area |

Timeframes

| Display | Timeframe value | |---|---| | 1 min | '1m' | | 5 min | '5m' | | 15 min | '15m' | | 30 min | '30m' | | 1 hour | '1h' | | 4 hours | '4h' | | 1 day | '1d' | | 1 week | '1w' | | 1 month | '1mo' |

Indicators

36 indicators across 5 categories. Use id values in defaultIndicators / allowedIndicators.

Overlay (renders on the main chart)

| ID | Name | |---|---| | sma | Simple Moving Average | | ema | Exponential Moving Average | | wma | Weighted Moving Average | | dema | Double EMA | | tema | Triple EMA | | hma | Hull Moving Average | | vwma | Volume-Weighted MA | | rma | RMA / Smoothed MA | | bb | Bollinger Bands | | keltner | Keltner Channels | | donchian | Donchian Channels | | ichimoku | Ichimoku Cloud | | parabolic-sar | Parabolic SAR | | supertrend | Supertrend | | twap | TWAP |

Sub-pane: Oscillators

| ID | Name | |---|---| | rsi | Relative Strength Index | | macd | MACD | | stoch | Stochastic | | stoch-rsi | Stochastic RSI | | cci | CCI | | williams-r | Williams %R | | awesome-oscillator | Awesome Oscillator | | momentum | Momentum | | roc | Rate of Change |

Sub-pane: Trend / Strength

| ID | Name | |---|---| | adx | Average Directional Index | | dmi | Directional Movement Index | | aroon | Aroon |

Sub-pane: Volatility

| ID | Name | |---|---| | atr | Average True Range | | bb-bandwidth | Bollinger Bandwidth | | hist-volatility | Historical Volatility | | stdev | Standard Deviation |

Sub-pane: Volume

| ID | Name | |---|---| | obv | On-Balance Volume | | mfi | Money Flow Index | | chaikin-mf | Chaikin Money Flow | | volume-osc | Volume Oscillator | | klinger | Klinger Oscillator |

Drawing Tools

68 tools across 9 groups. Use tool IDs in allowedDrawingTools.

| Group | Tools | |---|---| | Lines | trendline, ray, infoline, extendedline, trendangle, hline, hray, vline, crossline | | Channels | parallelchannel, regressiontrend, flattopbottom, disjointchannel | | Pitchforks | pitchfork, schiffpitchfork, modifiedschiff, insidepitchfork | | Fibonacci | fibretracement, fibextension, fibchannel, fibtimezone, fibspeedfan, fibtimeext, fibcircles, fibspiral, fibarcs, fibwedge, pitchfan | | Gann | gannfan, gannsquare, gannbox | | Forecasting | longposition, shortposition, forecast, barspattern, ghostfeed, pricerange, daterange, datepricerange, projection | | Shapes | rectangle, rotatedrect, circle, ellipse, triangle, path, polyline, arc, curve, doublecurve | | Annotations | text, callout, note, pricenote, pin, flagmark, arrow, arrowup, arrowdown, arrowleft, arrowright, signpost | | Brush | brush, highlighter |

Keyboard Shortcuts

| Shortcut | Tool | |---|---| | ⌥T (Alt+T) | Trend Line | | ⌥H (Alt+H) | Horizontal Line | | ⌥J (Alt+J) | Horizontal Ray | | ⌥V (Alt+V) | Vertical Line | | ⌥C (Alt+C) | Cross Line | | Escape | Deactivate tool, return to cursor | | Ctrl/⌘+Z | Undo | | Ctrl/⌘+Shift+Z | Redo | | Delete / Backspace | Delete selected drawing |

Theming & Colors

The theme option sets the base palette ('dark' or 'light'). Override any color using colors:

createCryHubChart(el, {
  // ...
  theme: 'dark',
  colors: {
    toolbar: {
      active: '#f59e0b',
      activeText: '#000000',
    },
    candle: {
      upBody:   '#00bfa5',
      downBody: '#ff3d00',
    },
  },
});

Full ColorScheme structure

interface ColorScheme {
  background: string;
  backgroundSecondary: string;   // sub-pane backgrounds
  grid: string;
  border: string;
  text: string;
  textSecondary: string;
  textMuted: string;
  crosshair: string;
  candle: {
    upBody: string;
    upWick: string;
    downBody: string;
    downWick: string;
  };
  volume: {
    up: string;
    down: string;
  };
  priceScale: {
    text: string;
    currentPriceLine: string;
    currentPriceText: string;
    currentPriceBg: string;
  };
  toolbar: {
    background: string;
    text: string;
    active: string;
    activeText: string;
    hover: string;
    border: string;
    flyoutBg: string;
    flyoutBorder: string;
  };
  subPane: {
    background: string;
    border: string;
    handleBg: string;
  };
  modal: {
    overlay: string;
    background: string;
    border: string;
    inputBg: string;
    inputBorder: string;
  };
  badge: {
    up: string;
    down: string;
    upText: string;
    downText: string;
  };
}

Internationalization

| locale | Layout | Labels | Numbers | |---|---|---|---| | 'en' | Left-to-right | English | Western (0–9) | | 'fa' | Right-to-left | English* | Western (0–9) |

*In v1, locale: 'fa' mirrors the layout only. All chart labels remain in English — standard practice for Persian financial platforms (Nobitex, Wallex, Ramzinex).

When locale: 'fa':

• Drawing toolbar moves to the right side
• All layout elements mirror horizontally
• Flyout panels open to the left
• Touch/drag directions mirror accordingly

Multi-Instance Support

Multiple independent charts on the same page are fully supported. Each widget creates its own WebSocket connection, data manager, drawing manager, and localStorage namespace.

<cryhub-chart id="chart-btc"></cryhub-chart>
<cryhub-chart id="chart-eth"></cryhub-chart>

<script type="module">
  import { createCryHubChart } from '@cryhub/chart-widget';

  createCryHubChart(document.getElementById('chart-btc'), {
    token: TOKEN,
    symbol: 'btcusdt',
    currencies: ['usdt'],
    defaultCurrency: 'usdt',
    timeframes: ['15m', '1h', '4h'],
    defaultTimeframe: '15m',
    theme: 'dark',
    locale: 'en',
  });

  createCryHubChart(document.getElementById('chart-eth'), {
    token: TOKEN,
    symbol: 'ethusdt',
    currencies: ['usdt'],
    defaultCurrency: 'usdt',
    timeframes: ['15m', '1h', '4h'],
    defaultTimeframe: '1h',
    theme: 'dark',
    locale: 'en',
  });
</script>

Development

Prerequisites

• Node.js 20+
• npm 10+

Setup

# Clone and install
git clone <repo>
cd chart-widget
npm install

# Copy env template and fill in your CryHub dev tokens
cp .env.example .env.local
# Edit .env.local with real tokens

Start dev server

npm run dev
# → http://localhost:5173

The demo page shows four independent chart instances testing different configurations.

Building

Library build (ES module + IIFE + TypeScript declarations)

npm run build:lib

Outputs to dist/:

| File | Format | Use | |---|---|---| | cryhub-chart.es.js | ES module | import / NPM | | cryhub-chart.iife.js | IIFE | <script src="..."> | | index.d.ts + tree | TypeScript | IDE autocomplete |

Type check only

npm run type-check

Docker

Run the demo environment without installing Node locally:

# Copy and fill in tokens
cp .env.example .env.local

# Start
docker compose up

# → Demo at http://localhost:5173

The container mounts the project directory with a volume, so edits to src/ and demo/ hot-reload instantly via Vite HMR.

Real-World Example

import { createCryHubChart } from '@cryhub/chart-widget';

createCryHubChart(document.getElementById('chart'), {
  // Auth
  token: process.env.CRYHUB_TOKEN,

  // Market data
  symbol: 'btcusdt',
  symbolLabel: 'BTC/USDT',
  currencies: ['tmn'],
  defaultCurrency: 'tmn',
  timeframes: ['1m', '5m', '15m', '30m', '1h', '4h', '1d'],
  defaultTimeframe: '15m',

  // Branding
  brandName: 'IRBTC',
  brandLogo: 'https://irbtc.com/logo.png',

  // Appearance
  theme: 'dark',
  locale: 'fa',
  colors: {
    toolbar: { active: '#f59e0b', hover: '#1e293b' },
  },

  // Features
  allowChartSettings: true,
  showDrawingTools: true,
  showIndicators: true,
  showVolumeProfile: true,
  showFullscreen: true,

  // Defaults
  defaultIndicators: [
    { id: 'sma', params: { length: 7,  color: '#e74c3c' } },
    { id: 'sma', params: { length: 25, color: '#3498db' } },
    { id: 'sma', params: { length: 99, color: '#2ecc71' } },
  ],
  lockDefaultIndicators: true,
  maxSubPanes: 3,
});

License

Proprietary — © CryHub. All rights reserved.