Skip to main content

Compare

The Compare feature provides comprehensive symbol comparison capabilities for the financial charting library. This system enables users to overlay and compare multiple financial instruments on the same chart, supporting both price-based and percentage-based comparisons.

Key Features​

  • Multiple symbol comparison (up to 10 symbols)
  • Price-based comparison
  • Percentage-based comparison
  • Customizable comparison colors and styles
  • Comparison legend display
  • Real-time comparison updates
  • Historical data synchronization

Architecture / Behavior​

The compare system follows a layered architecture:

  1. UI Layer: Right sidebar compare panel with symbol selection
  2. API Layer: ChartApi and GlobalApi compare methods
  3. State Layer: ChartStore manages compare symbols state
  4. Rendering Layer: SeriesRenderer handles comparison rendering

The comparison flow: UI → ChartApi → ChartStore → SeriesRenderer → Canvas → UI.

API Usage​

Initialization​

The compare feature is enabled by default in the chart configuration:

const chart = Chart.create(document.getElementById('container'), {
  // ... other options
  enabled_features: ['compare'], // Enable compare functionality
});

Methods​

ChartApi.addCompareSymbol() - Add a symbol for comparison:

// Add AAPL for price comparison
chart.getApi().addCompareSymbol({
  symbol: 'AAPL',
  type: 'price', // or 'percentage'
  color: '#FF6B6B',
  visible: true
});

// Add TSLA for percentage comparison
chart.getApi().addCompareSymbol({
  symbol: 'TSLA',
  type: 'percentage',
  color: '#4ECDC4',
  visible: true
});

ChartApi.getCompareSymbols() - Get all comparison symbols:

const compareSymbols = chart.getApi().getCompareSymbols();
console.log('Compare symbols:', compareSymbols);

ChartApi.removeCompareSymbol() - Remove a comparison symbol:

// Remove comparison symbol by ID
chart.getApi().removeCompareSymbol('compare_123');

Configuration Options​

OptionTypeDefaultDescription
enabled_featuresstring[]['compare']Enable/disable compare functionality
compare_max_symbolsnumber10Maximum number of symbols to compare
compare_default_type`'price''percentage'`'price'
compare_opacitynumber0.8Opacity for comparison series

Events​

  • compare:added - Fired when comparison symbol is added
  • compare:removed - Fired when comparison symbol is removed
  • compare:updated - Fired when comparison symbol is updated

Customization​

  • UI styling can be customized via CSS classes
  • Comparison colors can be customized per symbol
  • Comparison type can be customized per symbol
  • Legend display can be customized

Use Cases​

  • Comparing stock performance against indices
  • Analyzing correlated assets
  • Building relative strength indicators
  • Creating custom market breadth analysis
  • Integration with trading strategies

Limitations​

  • Requires data feed implementation of getBars() method
  • Performance depends on number of comparison symbols
  • Some comparison types may not be supported by all data feeds
  • Limited to symbols supported by connected data feeds

✅ Supported​

  • Comparison API methods exist and are functional
  • Multiple symbol support
  • Price and percentage comparison
  • Real-time updates
  • Historical data loading

❌ Not Supported​

  • Cross-exchange comparison
  • Multi-timeframe comparison
  • Advanced statistical comparison

⚠️ Partial / External​

  • Backend API integration requires custom data feed implementation
  • Comparison calculations require custom implementation

Feature Classification​

Core Feature - Fundamental functionality required for basic chart operation

Dependencies​

  • Requires backend? Yes (data feed API)
  • Requires storage? No
  • Requires real-time data? Yes (for live updates)
  • Requires UI controls? Yes (compare panel)

Missing Implementation Analysis​

The compare functionality is fully implemented and production-ready. All core comparison capabilities are present in the codebase with proper error handling and validation mechanisms.

Consistency Validation​

The compare API follows the same pattern as other API methods with consistent promise-based return values and error handling. Naming conventions are consistent with other features.

UI vs API Separation​

  • UI handles: Symbol selection, comparison type selection, visual feedback
  • API exposes: addCompareSymbol(), getCompareSymbols(), removeCompareSymbol() methods
  • Must implement manually: Custom data feed comparison logic

User Flow​

  1. User selects symbol from compare panel
  2. ChartApi validates symbol
  3. ChartStore adds symbol to state
  4. DataFeed requests historical data
  5. SeriesRenderer renders comparison series
  6. UI updates legend and controls

Integration with Existing Docs​

This feature should be linked from:

  • Charting section → Right Sidebar
  • API Reference → ChartApi
  • Connecting Data → Data Feeds
  • Getting Started → Quick Start Guide