| name | pinescript-visual |
| description | Use when adding visual output to Pine Script — plot()/plotshape()/bgcolor()/fill()/hline(), label.*, line.*, box.*, table.*, map.*, matrix.*, log.*, alerts, and drawing object limits. |
Pine Script Plotting & Drawing
1. Plotting Functions
plot() — lines and value series
//@version=5
indicator("plot() demo", overlay = true)
ma_fast = ta.ema(close, 9)
ma_slow = ta.ema(close, 21)
plot(ma_fast, title = "EMA 9", color = color.blue, linewidth = 2)
plot(ma_slow, title = "EMA 21", color = color.orange, linewidth = 1,
style = plot.style_line)
Plot styles:
| Constant | Appearance |
|---|
plot.style_line | Continuous line (default) |
plot.style_linebr | Line that breaks at na values |
plot.style_histogram | Vertical bars from a baseline (default 0) |
plot.style_columns | Filled columns from a baseline |
plot.style_area | Filled area below the line |
plot.style_areabr | Filled area, breaks at na |
plot.style_circles | Dots at each bar |
plot.style_cross | Cross marks at each bar |
plot.style_stepline | Staircase (holds value until next bar) |
plotshape() — marker shapes at specific bars
plotshape(buy, title = "Buy signal", shape = shape.triangleup,
location = location.belowbar, color = color.green,
text = "BUY", textcolor = color.white, size = size.small)
Common shape.* constants: shape.triangleup, shape.triangledown, shape.circle, shape.square, shape.diamond, shape.cross, shape.xcross, shape.arrowup, shape.arrowdown, shape.flag, shape.labelup, shape.labeldown.
Common location.* constants: location.abovebar, location.belowbar, location.top, location.bottom, location.absolute.
plotchar() — single Unicode character as marker
plotchar(gap_up, title = "Gap up", char = "▲",
location = location.abovebar, color = color.teal, size = size.tiny)
plotarrow() — directional arrows scaled by value
// Positive values → up arrows; negative values → down arrows
// Arrow height scales with the absolute value of series
plotarrow(momentum, title = "Momentum arrow",
colorup = color.green, colordown = color.red)
bgcolor() — color the chart background
bgcolor(overbought_zone ? color.new(color.red, 85) : na, title = "Overbought")
barcolor() — recolor the price bars
barcolor(close > open ? color.new(color.teal, 20)
: close < open ? color.new(color.maroon, 20)
: color.gray)
barcolor() affects only the primary chart bars — no effect in a sub-pane indicator.
fill() — shade area between two plots
p_upper = plot(bb_upper, "BB Upper", display = display.none)
p_lower = plot(bb_lower, "BB Lower", display = display.none)
fill(p_upper, p_lower, color = color.new(color.blue, 88))
A common pattern is to create "invisible" helper plots (display = display.none) solely for use as fill() boundaries.
hline() — static horizontal reference line
hline(70, "Overbought", color = color.red, linestyle = hline.style_dashed)
hline(50, "Midpoint", color = color.gray, linestyle = hline.style_dotted)
hline(30, "Oversold", color = color.green, linestyle = hline.style_dashed)
hline()'s price takes an input int/float — only const or input values; the price level cannot vary bar by bar.
2. label.* — Labels
Labels attach text annotations to specific chart coordinates.
Constructor
label.new(
x, // bar index (int) or timestamp if xloc = xloc.bar_time
y, // price level (float)
text = "",
xloc = xloc.bar_index,
yloc = yloc.price,
color = color.blue,
style = label.style_label_down,
textcolor = color.white,
size = size.normal,
textalign = text.align_center,
tooltip = ""
)
Setter functions
| Function | What it changes |
|---|
label.set_x(id, x) | Bar index or timestamp |
label.set_y(id, y) | Price level |
label.set_xy(id, x, y) | Position in one call |
label.set_text(id, text) | Label text string |
label.set_color(id, color) | Label background/border color |
label.set_textcolor(id, color) | Text color |
label.set_style(id, style) | Label style constant |
label.set_size(id, size) | Text/marker size |
label.set_tooltip(id, tooltip) | Tooltip text on hover |
Getter functions
| Function | Returns |
|---|
label.get_x(id) | series int — current x |
label.get_y(id) | series float — current y |
label.get_text(id) | series string — current text |
Other functions
label.copy(id), label.delete(id), label.all (array of all labels)
label.style_* constants
| Constant | Appearance |
|---|
label.style_label_down | Callout box pointing downward (default) |
label.style_label_up | Callout box pointing upward |
label.style_label_left | Callout box pointing left |
label.style_label_right | Callout box pointing right |
label.style_circle | Filled circle |
label.style_cross | Plus sign |
label.style_xcross | X mark |
label.style_diamond | Diamond shape |
label.style_flag | Flag marker |
label.style_square | Filled square |
label.style_triangleup | Upward-pointing triangle |
label.style_triangledown | Downward-pointing triangle |
label.style_arrowup | Arrow pointing up |
label.style_arrowdown | Arrow pointing down |
label.style_none | Invisible — text only |
Supporting constants
| Group | Values |
|---|
size.* | size.auto, size.tiny, size.small, size.normal, size.large, size.huge |
xloc.* | xloc.bar_index (default), xloc.bar_time |
yloc.* | yloc.price (default), yloc.abovebar, yloc.belowbar |
text.align_* | text.align_left, text.align_center, text.align_right |
Gotcha — label count limit: Default max is 50 labels. Raise to 500 with max_labels_count = 500 in the indicator() or strategy() declaration.
3. line.* — Lines
Lines draw a segment (or ray) between two chart coordinates.
Constructor
line.new(
x1, y1, // start point
x2, y2, // end point
xloc = xloc.bar_index,
extend = extend.none,
color = color.blue,
style = line.style_solid,
width = 1
)
Setter and getter functions
| Function | Description |
|---|
line.set_x1/y1/x2/y2(id, val) | Move individual coordinates |
line.set_xy1/xy2(id, x, y) | Set point in one call |
line.set_color/style/width(id, val) | Visual properties |
line.set_extend(id, extend) | Change extend mode |
line.get_x1/y1/x2/y2(id) | Read coordinates |
line.get_price(id, x) | Price on the line at bar index x (interpolated) |
line.copy(id), line.delete(id), line.all | Management |
line.style_* constants
line.style_solid, line.style_dashed, line.style_dotted, line.style_arrow_left, line.style_arrow_right, line.style_arrow_both
extend.* constants
| Constant | Description |
|---|
extend.none | Line drawn only between x1 and x2 |
extend.left | Ray extending infinitely to the left |
extend.right | Ray extending infinitely to the right |
extend.both | Full infinite line through both points |
Gotcha — line count limit: Default max is 50 lines. Raise to 500 with max_lines_count = 500.
4. box.* — Boxes
Boxes draw filled rectangles between two price levels over a range of bars.
Constructor
box.new(
left, top, right, bottom,
border_color = color.blue, border_width = 1, border_style = line.style_solid,
extend = extend.none, xloc = xloc.bar_index,
bgcolor = color.new(color.blue, 90),
text = "", text_size = size.auto,
text_color = color.black, text_halign = text.align_center,
text_valign = text.align_center
)
Setter functions
box.set_left/top/right/bottom, box.set_lefttop/rightbottom, box.set_border_color/width/style, box.set_bgcolor, box.set_extend, box.set_text/text_color/text_size
Getter functions
box.get_left/top/right/bottom
Other
box.copy(id), box.delete(id), box.all
Gotcha — box count limit: Default max is 50 boxes. Raise to 500 with max_boxes_count = 500.
5. table.* — Tables
Tables display text in a fixed grid anchored to a corner of the chart pane.
Constructor
table.new(
position = position.top_right,
columns = 2,
rows = 3,
bgcolor = color.new(color.gray, 80),
frame_color = color.gray,
frame_width = 1,
border_color = color.gray,
border_width = 1
)
Cell functions
table.cell(table_id, column, row,
text = "", text_color = color.black, text_size = size.normal,
bgcolor = na, tooltip = "")
Partial updates: table.cell_set_text, table.cell_set_bgcolor, table.cell_set_text_color, table.cell_set_text_size
Other: table.merge_cells(id, c1, r1, c2, r2), table.clear(id, c1, r1, c2, r2), table.delete(id)
position.* constants
position.top_left, position.top_center, position.top_right, position.middle_left, position.middle_center, position.middle_right, position.bottom_left, position.bottom_center, position.bottom_right
Gotcha — create with var or in barstate.islast: Creating a new table on every bar wastes resources and flickers. Use var table stats = table.new(...) and update cells with table.cell().
6. map.* — Maps
Maps store key-value pairs with O(1) lookup.
var map<string, float> tf_closes = map.new<string, float>()
map.put(tf_closes, "Daily", daily_close)
val = map.get(tf_closes, "Daily") // na if not found
exists = map.contains(tf_closes, "Daily") // bool
Core functions: map.put, map.put_all, map.get, map.contains, map.remove, map.keys, map.values, map.size, map.clear, map.copy
Valid key types: int, float, bool, string, color. Max 50,000 pairs per map.
7. matrix.* — Matrices
Two-dimensional typed arrays with linear algebra support.
m = matrix.new<float>(3, 3, 0.0) // 3×3 float matrix, all zeros
matrix.set(m, 0, 0, 1.0)
val = matrix.get(m, 0, 0)
Element access
matrix.get/set/fill, matrix.row/col (extract as array), matrix.rows/columns/elements_count, matrix.reshape
Row/column manipulation
matrix.add_row/add_col, matrix.remove_row/remove_col, matrix.swap_rows/swap_columns, matrix.submatrix, matrix.reverse, matrix.concat
Linear algebra
matrix.transpose, matrix.det, matrix.inv, matrix.pinv, matrix.rank, matrix.trace, matrix.eigenvalues, matrix.eigenvectors, matrix.kron, matrix.mult
Statistics
matrix.avg, matrix.max, matrix.min, matrix.sum, matrix.diff, matrix.median, matrix.mode
Boolean inspectors
matrix.is_square, matrix.is_symmetric, matrix.is_diagonal, matrix.is_identity, matrix.is_zero, matrix.is_triangular, matrix.is_stochastic, matrix.is_binary
Gotcha: matrix.det(), matrix.inv(), matrix.eigenvalues() require square matrices. Row/column indices are 0-based.
8. log.* — Logging
| Function | Severity |
|---|
log.info(message) | Informational |
log.warning(message) | Warning |
log.error(message) | Error |
All accept format-string overloads: log.info("RSI at bar {0}: {1}", bar_index, rsi_val)
Gotcha: Log output appears only in the Pine Logs panel (Pine Editor → Logs tab), not on the chart.
9. Alerts
alert() — flexible, works in both indicators and strategies
if cross_up
alert(str.format("BUY signal on {0}", syminfo.ticker), alert.freq_once_per_bar)
alertcondition() — static, indicators only
alertcondition(cross_up, title = "EMA Cross Up", message = "Fast crossed above Slow")
- Indicators only — compile error in
strategy().
- Must be at global scope (not inside any
if or function body).
title and message must be const string — no dynamic construction.
alert.freq_* constants
| Constant | Fires |
|---|
alert.freq_once_per_bar | At most once per bar |
alert.freq_once_per_bar_close | Only on confirmed close |
alert.freq_all | Every matching tick |
10. Drawing Object Limits Summary
| Object | Default max | Max via declaration param |
|---|
| Labels | 50 | 500 (max_labels_count = 500) |
| Lines | 50 | 500 (max_lines_count = 500) |
| Boxes | 50 | 500 (max_boxes_count = 500) |
| Tables | No hard per-object limit | — |
| Maps | — | 50,000 pairs per map instance |
