Custom Drawings

Use defineDrawing to add chart-scoped Canvas drawings such as trend lines, price segments, annotations, or other interactive overlays.

const definition = defineDrawing<Config, CompleteConfig>({
  type: 'custom:price-segment',
  displayName: 'PriceSegment',
  parseConfig,
  draw,
  hitTest,
  onHover,
  onClick,
  onDrag,
});

const PriceSegment = definition.Component;

Register the definition on each chart that uses its component:

<Chart data={data} drawingDefinitions={[definition]}>
  <Panel>
    <Candlesticks />
    <PriceSegment
      startIndex={10}
      startValue={120}
      endIndex={30}
      endValue={135}
    />
  </Panel>
</Chart>

Definitions are local to a chart. A custom drawing type must be a non-empty string and must not collide with another custom drawing registered on the same chart.

defineDrawing

defineDrawing accepts:

Property	Type	Description
type	string	Stable drawing type used in JSX metadata and config objects.
displayName	string	Optional React component display name.
parseConfig	(config, panelId, drawingIndex) => completeConfig	Applies defaults and returns the runtime drawing config.
draw	(renderContext) => void	Draws the custom drawing on Canvas.
hitTest	`(hitTestContext) => DrawingHitTestResult	null`
onHover	(hit, hitTestContext) => void	Optional drawing-level hover handler.
onClick	(hit, hitTestContext) => void	Optional drawing-level click handler.
onDragStart	(hit, hitTestContext) => void	Optional drag-start handler.
onDrag	(dragContext) => void	Optional drag handler.
onDragEnd	(hit, hitTestContext) => void	Optional drag-end handler.

Config Types

Extend DrawingConfig for JSX/user config and DrawingConfigComplete for the parsed runtime config:

interface PriceSegmentConfig extends DrawingConfig {
  type: 'custom:price-segment';
  startIndex: number;
  startValue: number;
  endIndex: number;
  endValue: number;
  color?: string;
}

interface PriceSegmentConfigComplete extends DrawingConfigComplete {
  type: 'custom:price-segment';
  startIndex: number;
  startValue: number;
  endIndex: number;
  endValue: number;
  color: string;
}

The generated component accepts the config properties except type; the definition supplies that automatically.

Render Helpers

Drawing render and hit-test contexts provide helpers for mapping data coordinates into chart pixels:

Helper	Description
xForIndex(index)	Returns the x-position for a bar index.
xForTimestamp(timestamp, nearest?)	Returns the x-position for a timestamp.
valueToY(value, scaleKey?)	Returns the y-position for a value.

scaleKey can be set on a drawing config when it should use a specific panel scale. If omitted, the chart uses the panel's available layer scale.

Chart Callbacks

Use chart-level callbacks when the parent component needs to react to drawing interactions:

<Chart
  data={data}
  drawingDefinitions={[priceSegment]}
  onDrawingHover={setHoveredDrawing}
  onDrawingClick={handleDrawingClick}
>
  ...
</Chart>

TypeScript

interface DrawingConfig {
  id?: string;
  type: string;
  visible?: boolean;
  scaleKey?: string;
  [key: string]: unknown;
}

interface DrawingConfigComplete extends DrawingConfig {
  id: string;
  type: string;
  visible: boolean;
}

interface DrawingHit {
  drawingId: string;
  drawingType: string;
  panelId: string;
  target?: string;
  cursor?: string;
  data?: unknown;
}