Version: 1.0.0

Custom primitives

Primitives are lightweight render objects attached directly to the chart canvas — either as pane primitives (background overlays) or series primitives (foreground annotations on the price scale).

Overview

Primitives are plain JavaScript classes that implement a drawing interface. They receive attached() and detached() lifecycle callbacks, and are attached to the chart via chart.attachPrimitive(primitive).

Pane Primitive (Background Layer)

Implement drawBackground(ctx, chartW, chartH) to render behind candles and indicators:

class CustomTextOverlayPrimitive {
  drawBackground(ctx, chartW, chartH) {
    ctx.fillStyle = 'rgba(255, 255, 255, 0.08)';
    ctx.font = 'bold 24px Inter';
    ctx.fillText('SANDBOX', 25, 25);
  }
}

Series Primitive (Foreground + Price Scale)

Implement draw(ctx, chartW, chartH) for the main pane and drawPriceScale(ctx, priceScaleW, chartH) for the Y-axis annotation:

class CustomPriceLinePrimitive {
  draw(ctx, chartW, chartH) {
    const y = this.chart.priceToY(this.price);
    ctx.strokeStyle = '#2962ff';
    ctx.setLineDash([6, 4]);
    ctx.beginPath();
    ctx.moveTo(0, y); ctx.lineTo(chartW, y);
    ctx.stroke();
  }
}

Attach & Detach

// Attach
const priceLine = new CustomPriceLinePrimitive(25000, '#2962ff', 'Target');
chart.attachPrimitive(priceLine);

// Detach
chart.detachPrimitive(priceLine);