imp_trading_chart

A controller-driven trading line chart for Flutter
Inspired by TradingView Lightweight Charts

🚀 Overview

imp_trading_chart is a rendering-first trading line chart for Flutter.

It is not a widget-heavy chart, but a CustomPainter + viewport-driven engine designed for performance, precision, and scalability.

Built specifically for:

  • 📈 Financial & stock market apps
  • 💹 Crypto & trading platforms
  • ⚡ Real-time price feeds
  • 🧠 Viewport-limited rendering for large datasets

Quick Start

import 'package:imp_trading_chart/imp_trading_chart.dart';

ImpChart.trading(candles: candles);

// Inspect by holding without allowing drag or zoom.
ImpChart.trading(
  candles: candles,
  gestureMode: ChartGestureMode.holdOnly,
);

The current renderer draws a line through each candle's close price. The Candle model also carries OHLC and optional volume values; candle bodies and volume panels are planned for a later release.

Gesture Modes

Mode Pan Pinch Double tap reset Hold crosshair
mixed Yes Yes Yes Yes
navigation Yes Yes Yes No
holdOnly No No No Yes
panOnly Yes No No No
zoomOnly No Yes No No
none No No No No

trading defaults to mixed; simple and compact default to navigation; minimal stays non-interactive unless given a mode or overrides. Existing enableGestures: false always disables chart gestures. To change one action:

ImpChart.trading(
  candles: candles,
  gestureOverrides: const ChartGestureOverrides(
    pinchZoom: false,
    doubleTapReset: false,
  ),
);

Gesture modes are per widget. Charts may share one controller yet use different modes. Modes do not change programmatic controller commands or live following. The Go to live button remains tappable when a chart is in none or holdOnly.

✨ Visual Themes & Styles

🎬 Live Interaction Demos

🌎 Real App Integration

▶️ Full Market Simulation

✋ Drag / Pan Viewport

🔍 Pinch-to-Zoom

📊 Chart Variants

Variant Use Case
Trading Interactive close-price line chart
Simple Clean chart with labels
Compact Dashboards & lists
Minimal Sparklines & previews

🧠 Engine-First Architecture

Candle Data (List<Candle>)
        ↓
ChartEngine (viewport, scaling, mapping)
        ↓
CustomPainter (pixels only)

Why this matters

  • ❌ No widget-per-candle
  • ❌ No DateTime math in render loop
  • ❌ No unnecessary rebuilds

✅ Only visible candles are processed Pan and zoom update a bounded viewport; rendering processes the visible slice. The reproducible 10k-candle comparison benchmark is in test/benchmark/.

📦 Installation

dependencies:
  imp_trading_chart: ^0.2.1

🚀 Basic Usage

ImpChart.trading(
  candles: candles
);

Controller Usage

final controller = ImpChartController(
  defaultVisibleCount: 120,
);

ImpChart.trading(
  candles: candles,
  controller: controller,
);

controller.scrollToLatest();
controller.zoomIn();

Live Update UX

imp_trading_chart now uses a preserve-context live-update policy:

  • If the chart is at or near the latest candles, it keeps following live data.
  • If the user pans into older history, incoming candles update the data without force-scrolling.
  • If new candles arrive while detached, the chart shows a Go to live (+count) action that scrolls back to the latest candles on tap.
  • Calling scrollToLatest() or resetting the viewport restores follow-latest behavior.

The internal near-latest threshold is currently 3 candles.

Architecture Highlights

  • ImpChart stays easy to use and keeps the controller optional.
  • ImpChartController is the public orchestration API for pan, zoom, reset, fit-all, scroll-to-latest, and live updates.
  • ChartPainter is now a rendering shell that delegates to focused internal renderers for line, grid, axis labels, current price, ripple, and crosshair drawing.
  • Widget-only mechanics are split into focused internal helpers for pulse animation, gesture translation, and live-update affordances.
  • PaddingResolver owns axis/current-price layout spacing so renderers stay drawing-focused.

🕯 Candle Model

Candle(
  time: 1700000000,
  open: 100,
  high: 120,
  low: 90,
  close: 110,
);

⚠️ The engine does not aggregate data.

🧪 Example App

A complete interactive demo is included in the example/ folder.

cd example
flutter run

📚 Documentation

🔒 Public API Stability

Only these are public & stable:

  • ImpChart
    • ImpChartController
    • ChartGestureMode and ChartGestureOverrides
    • Controller snapshots and ChartEvent
  • Candle
  • ChartStyle
  • ChartLayout
  • LabelStyles

🚧 Roadmap

  • Indicator overlays (MA, EMA, VWAP)
  • Additional theme presets
  • Extended visual regression coverage

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for guidelines on how to get started, project structure, and our CODE_OF_CONDUCT.md.

For a deep dive into the engine's internals, check out ARCHITECTURE.md.

📌 Stability & Versioning

This project follows Semantic Versioning (semver).

  • v0.x.x: Public API is considered stable but minor breaking changes may occur in minor versions while we approach 1.0.
  • Internal APIs: Everything under lib/src/ is considered internal and is not part of the stable public API. Use with caution.

📄 License

MIT License. See LICENSE for details.

Libraries

imp_trading_chart
imp_trading_chart