Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.darvas.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
​
handle.set(opts)
void
Mutate the entity in place. Only the provided keys are updated; others remain unchanged. No-ops silently if the generation is stale.
​
handle.clone(newKey)
handle
Copy the entity to a new key with a fresh generation. Returns a handle to the clone.
​
handle.delete()
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

TypePer-type limitGlobal limit
Line500-
Box500-
Label500-
Marker500-
LineFill500-
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.