Plotting
A script puts a value on the chart by calling an output function. plot is the one you will reach for first. It draws a series of numbers, one point per bar.
Every output call sits at the top level
Every chart-output function must be called at the top level of a script. Call one inside a branch, inside a loop, or inside a function you wrote yourself, and the script is rejected with an error saying the call must be made in the global scope. The check is structural, not advisory: a branch body opens a further scope, and the interpreter tests the scope the call sits in.
This is rejected:
if (close > open) {
plot(close, color = color.green)
}A condition belongs in the colour argument, never around the call. The colour parameter is series-form, so it may change from bar to bar. The call itself stays where it is.
c = color.red
if (close > open) {
c := color.green
}
plot(close, color = c)The rule holds for fills, levels, bar colouring, backgrounds, and text and markers alike. To draw a mark on some bars and not others, use a marker function: those take the condition as their first argument.
plot
plot(series float series, const string title, series color color, input int linewidth, input plotStyle style, input bool trackprice, input float histbase, input int offset, const bool force_overlay) → series plotplot takes nine parameters. Only the first, the series, is required. Every other parameter carries a default.
| Parameter | Type | Required | Notes |
|---|---|---|---|
series | series float | yes | The values to draw, one per bar. |
title | const string | no | The name of the plot. Const-form, so it cannot be built from series data. |
color | series color | no | The colour to draw in. Series-form, so it may differ on every bar. |
linewidth | input int | no | Input-form, so it is fixed for the run of the script. |
style | input plotStyle | no | Which member of the plot-style set to draw. |
histbase | input float | no | Input-form, so it is fixed for the run of the script. |
offset | input int | no | Input-form, so it cannot change from bar to bar. |
force_overlay | const bool | no | Sets this one plot’s overlay, separately from the script-wide setting. |
The signature also lists trackprice. Nothing reads it. It is type-checked and then ignored, so it has no effect on what you see, and you should leave it out.
plot returns a plot value. Keep that value in a variable and you can pass two plots to fill.
indicator("Close and midpoint")
plot(close, title = "Close", color = color.blue, linewidth = 2)
plot(hl2, title = "Midpoint", color = color.orange, style = plotStyle.stepLine)Titles
A title cannot be built from series data: it is const-form. Every output function defaults its title to the same word, so plots you leave untitled share one name rather than being numbered. Give each plot a title of its own.
Gaps
An na value in a plotted series leaves a gap on that bar. It does not draw a zero.
Overlay
The script-wide overlay setting and a single plot’s overlay are separate switches. The indicator declaration at the top of the script sets the script’s overlay. The force_overlay parameter sets that one plot’s.
Offsets
An offset cannot change from bar to bar. It is input-form wherever it appears, and plotcandle and plotbar have none at all.
The fixed sets
A plot style, a marker shape, a marker size and a label position are each chosen from a fixed set. The interpreter records the member you name and leaves its appearance to the chart.
| Set | Members | Named by |
|---|---|---|
plotStyle | line, linebr, area, areabr, smoothedArea, stepLine, stepLinebr, stepArea, stepAreabr, bar, histogram, scatter, triangular, cross | the style parameter of plot |
shape | xcross, cross, triangleup, triangledown, flag, circle, arrowup, arrowdown, labelup, labeldown, square, diamond | the shape parameter of plotshape |
size | auto, tiny, small, normal, large, huge | the size parameter of plotshape and plotchar |
location | abovebar, belowbar, top, bottom, absolute | the location parameter of plotshape and plotchar |
hlineStyle | solid, dashed, dotted | the style parameter of hline |
Name a member with the set in front of it, as in plotStyle.histogram or location.abovebar.
Chart points
A chart point is a value that carries three fields.
| Field | Type |
|---|---|
time | series int |
index | series int |
price | series float |
Five functions build one.
chartPoint.new(series int time, series int index, series float price) → series chartPointchartPoint.from_time(series int time, series float price) → series chartPointchartPoint.from_index(series int index, series float price) → series chartPointchartPoint.now(series float price) → series chartPointchartPoint.copy(series chartPoint id) → series chartPointchartPoint.new takes all three fields. chartPoint.from_time and chartPoint.from_index each take one coordinate and a price. chartPoint.now takes a price alone, and its price argument is optional. chartPoint.copy returns a copy of a chart point you already hold.
None of the output functions on this page takes a chart point.