Drawing entities overview

What are entities?

Drawing entities are interactive overlays on the chart canvas - Lines, Boxes, Labels, Markers, and LineFills. Unlike plot() which renders a value per bar, entities are keyed objects that persist across bars and can be mutated in place.

// Create a support line once; update its color based on price action
const support = Line("support", {
  x1: 0, y1: 42000,
  x2: 100, y2: 42000,
  color: "#22c55eFF",
});

onBar(() => {
  const close = ctx.close();
  // Turn red when price approaches the support
  support.set({ color: close < 42500 ? "#ef4444FF" : "#22c55eFF" });
});

The slot model

1 key = 1 slot. Each unique key string occupies exactly one slot in the entity registry. Calling the same factory with the same key overwrites the slot:

Last call wins.
The slot’s content (position, color, style) reflects the most recent call.
Persistent across bars - you do not need to recreate the entity every bar.

// Every bar this runs, it updates the SAME line slot - it does not create 500 lines
onBar(() => {
  Line("trend", {
    x1: ctx.i() - 20, y1: ta.lowest(ctx.low, 20),
    x2: ctx.i(),      y2: ctx.close(),
    color: "#22c55eFF",
  });
});

Generation tokens

Every time you call a factory (Line, Box, etc.) for a key, a new generation is allocated. The returned handle carries the key + generation pair internally as { __key, __gen, __kind }.

If you call Line("my-line", opts) twice, the second call allocates a fresh generation. Any handle returned from the first call will silently no-op on .set() or .delete() - its generation no longer matches the slot. Always use the return value from the most recent call.

let line = Line("sr", { x1: 0, y1: 100, x2: 10, y2: 100, color: "#22c55eFF" });

onBar(() => {
  if (someCondition) {
    // Correct: capture the new handle
    line = Line("sr", { x1: 0, y1: 95, x2: ctx.i(), y2: 95, color: "#ef4444FF" });
  }
  // Use the current handle to mutate
  line.set({ color: ctx.close() > 95 ? "#22c55eFF" : "#ef4444FF" });
});

Handle API

All entity factories return a handle with three methods:

void

Mutate the entity in place. Only the provided keys are updated; others remain unchanged. No-ops silently if the generation is stale.

handle

Copy the entity to a new key with a fresh generation. Returns a handle to the clone.

void

Remove the entity from the chart. No-ops silently if the generation is stale.

const h = Line("my-line", { x1: 0, y1: 0, x2: 1, y2: 1, color: "#22c55eFF" });

h.set({ color: "#ef4444FF", y2: 2 });  // mutate in place
const h2 = h.clone("my-line-copy");    // clone to new key
h.delete();                            // remove original

Entity budgets

Type	Per-type limit	Global limit
Line	500	-
Box	500	-
Label	500	-
Marker	500	-
LineFill	500	-
All entities combined	-	1500

Exceeding the per-type limit truncates silently with a warning in the console. See API limits for all budget values.

Entity types

Line

Anchored line segment between two bar/price coordinates.

Box

Rectangular zone with fill, border, text, and extend options.

Label

Text label pinned to a bar/price coordinate.

Marker

Icon shape (circle, diamond, arrow, etc.) at a point.

LineFill

Filled area between two Line entities.

Constants

linestyle, shape, size, extend, text.align enums.

Getting Started

Core Concepts

Plotting