mmflow Charts

Drawing tools

Add chart annotations through the public drawing API or let users place simple drawings directly on an embedded chart.

Supported primitives

Phase 5 exposes the annotation foundation: simple placement, selection, body dragging, delete, clear, and JSON import/export.

One-click tools

horizontalLine, verticalLine, and text place from one chart click. Text notes start with the default label Note.

Two-click tools

trendline, ray, and rectangle use two data-space anchors and stay attached through pan and zoom.

Interaction

Select drawings, drag unlocked drawings, press Delete or Backspace to remove, and press Escape to cancel the active tool.

Serialization

toJSON and fromJSON use a versioned { version: 1, drawings } document so the format can evolve safely.

Programmatic API

The drawing API lives on the same imperative IChartApi returned by createChart and exposed through React onReady.

api.drawings

import { createChart, type ChartDrawing } from "@mmflow/charts";

const chart = createChart({
  container: document.getElementById("chart")!,
  autosize: true,
});

const trendline: ChartDrawing = chart.drawings.add({
  type: "trendline",
  points: [
    { time: 1730000000000, price: 65000 },
    { time: 1730003600000, price: 67000 },
  ],
  style: { color: "#60a5fa" },
});

chart.drawings.update(trendline.id, {
  style: { color: "#facc15" },
});

const json = chart.drawings.toJSON();
const result = chart.drawings.fromJSON(json);

React usage

The React binding does not add a second drawing API. Use the existing onReady escape hatch or ChartHandle.api.

React onReady

"use client";

import { Chart } from "@mmflow/react";
import { createMmflowFeed } from "@mmflow/sdk";

export function AnnotatedChart() {
  return (
    <Chart
      feed={createMmflowFeed({ transport: "sse" })}
      symbol="BTC"
      resolution="1m"
      volume
      autosize
      onReady={(api) => {
        api.drawings.setActiveTool("trendline");
        api.drawings.add({
          type: "horizontalLine",
          points: [{ time: Date.now(), price: 65000 }],
          style: { color: "#facc15" },
        });
      }}
      style={{ height: 520 }}
    />
  );
}

JSON document

Import rejects unsupported versions or invalid drawings without mutating the current chart.

ChartDrawingsDocument

{
  "version": 1,
  "drawings": [
    {
      "id": "support-zone",
      "type": "rectangle",
      "points": [
        { "time": 1730000000000, "price": 64000 },
        { "time": 1730007200000, "price": 65500 }
      ],
      "style": {
        "color": "#f97316",
        "fill": "#f97316",
        "opacity": 0.16
      },
      "createdAt": 1730000000000,
      "updatedAt": 1730000000000
    }
  ]
}

Current limitations

These limits are intentional for the MVP and keep the SDK surface stable before broader annotation tools arrive.

No cloud persistence

Use toJSON/fromJSON for app-owned save and load flows.

No collaboration

Multi-user cursors, locks, and shared editing are not part of Phase 5.

No inline text editing

Update text labels through api.drawings.update(id, { label }).

No drawing alerts

Alerts from trendlines, zones, or levels remain a later runtime phase.

No public fib/channel tools yet

Terminal internals stay compatible, but the public SDK exposes only the six MVP tools.

No script-driven drawings

ChartScript indicators do not create, modify, or alert from drawing objects.

Repo starter template

Copy frontend/examples/drawing-tools for a read-only annotation template that adds drawings and round-trips versioned JSON locally.

Continue building

Move through the chart SDK docs without leaving the developer flow.