label.new() in Pine Script: Add Text Labels to Charts

The label.new function in Pine Script puts text annotations directly on your TradingView chart — prices, signals, calculations, whatever you need displayed at a specific bar and price level.

What is the label.new function in Pine Script?

The label.new function is Pine Script's built-in tool for creating text labels on your TradingView charts. You can place digital sticky notes exactly where you need them — marking support levels, showing trade signals, or displaying calculated values.

Here is the common coordinate-based form; see the official label documentation for the full overloads and current parameters:

label.new(x, y, text, xloc, yloc, color, style, textcolor, size, textalign, tooltip, text_font_family) → series label

Start with position and text, then add styling as needed.

Essential Parameters You Need to Know

Here are the parameters you'll reach for most often:

Position Parameters:

• x and y: Define where your label appears on the chart
• xloc and yloc: Control how the label positions relative to that point

Content Parameters:

• text: The actual message displayed in your label
• tooltip: Additional information shown when hovering over the label

Visual Parameters:

• color: Background color of the label
• style: Shape options (rectangle, circle, arrow, etc.)
• textcolor: Color of the text inside the label
• size: Controls label dimensions

If you're new to Pine Script, I'd suggest starting with this beginner's guide first. It covers the basics that make functions like label.new much easier to understand.

Modifying Labels After Creation

Labels in Pine Script are flexible after creation — you can update properties with the corresponding setter functions:

• label.set_x() and label.set_y() - Reposition individual coordinates
• label.set_xy() - Update both coordinates simultaneously
• label.set_text() - Change the displayed text
• label.set_color() - Modify background color
• label.set_style() - Switch between different shapes
• label.set_textcolor() - Update text color

Use label.set_xy() when both coordinates need to change together.

Practical Example: Dynamic Highest High Tracker

Here's a real example that tracks the highest price over the last 20 bars:

//@version=5
indicator("Dynamic High Tracker", overlay = true)

// Calculate the highest high over last 20 bars
lookback = 20
highestHigh = ta.highest(high, lookback)
highestOffset = ta.highestbars(high, lookback)

// Create a label that we'll reuse and move around
var label hiLabel = label.new(na, na, "High", xloc = xloc.bar_index, yloc = yloc.price, 
     color = color.new(color.green, 10), style = label.style_label_down, 
     textcolor = color.white, size = size.normal)

// Update on each last-bar execution, including when an old high expires
if barstate.islast
    label.set_xy(hiLabel, bar_index + highestOffset, highestHigh)
    label.set_text(hiLabel, "High: " + str.tostring(highestHigh, format.mintick))

var creates one label and the setters reuse it. ta.highestbars() supplies the non-positive offset of the selected highest bar. Updating on the last bar also moves the label when an older maximum leaves the 20-bar window, even if the current bar is not a new high.

Common Mistakes and How to Avoid Them

Number to String Conversion The text argument needs a string; convert numeric text with str.tostring(). The position arguments x and y remain numeric.

Memory Management By default, a script displays approximately its last 50 labels. Set max_labels_count in indicator() to raise the limit, up to 500; garbage collection removes older labels beyond the configured limit. Historical bars execute when the script loads, while realtime executions use rollback, so label count is not a wall-clock creation rate.

Performance Optimization Creating hundreds of labels can slow down your indicator. Use conditional logic to limit label creation and call label.delete() for old labels you no longer need. Limit annotations so the chart remains readable.

Advanced Label Styling Techniques

Pine Script offers several styling options to make your labels stand out:

Label Styles:

• label.style_label_up - Points upward
• label.style_label_down - Points downward
• label.style_label_left - Points left
• label.style_label_right - Points right
• label.style_circle - Circular shape
• label.style_square - Square shape

Size Options:

• size.tiny - Smallest labels
• size.small - Small labels
• size.normal - Default size
• size.large - Large labels
• size.huge - Largest labels

Why Labels Transform Your Trading Analysis

Labels can serve several chart-annotation purposes:

1. Level Marking: Identify crucial support and resistance zones
2. Signal Display: Show entry and exit points clearly
3. Value Broadcasting: Display real-time calculations and indicators
4. Condition Alerts: Highlight when specific market conditions occur
5. Historical Context: Mark important events or patterns

A label can explain what a plotted value represents. It does not verify the calculation or establish that a trading signal is correct.

Integration with Trading Strategies

Labels work well when combined with other Pine Script functions. For examples of how labels fit into complete trading systems, check out these Pine Script v6 strategy examples.

You might also find Pine Script's built-in functions list helpful for discovering more tools that pair with labels.

If coding isn't your thing but you want custom indicators, Pineify offers a visual approach — you can build indicators without writing Pine Script manually. Check the generated code and label placement on your intended chart.

Website: Pineify

Getting Started with Your First Label

Start with this simple template:

//@version=5
indicator("My First Label", overlay = true)

// Create a basic label
if bar_index % 10 == 0  // Show label every 10 bars
    label.new(bar_index, high, "Bar: " + str.tostring(bar_index), 
         color = color.blue, textcolor = color.white, 
         style = label.style_label_down)

This creates a label every 10 bars showing the current bar index. Change the condition to match your own signals — crossovers, support breaks, volume spikes — and watch your charts get more useful fast.

Frequently Asked Questions

▶What does label.new() do in Pine Script?

label.new() is a built-in Pine Script function that creates a text label directly on your TradingView chart at a specified price and bar position. It lets you display custom text, tooltips, and styled callout shapes to annotate signals, levels, or calculated values.

▶What are the required parameters for label.new() in Pine Script?

For the coordinate-based overload shown here, x sets the bar index or time and y sets the price coordinate. A separate overload accepts a chart point. All other parameters are optional — text, color, style, textcolor, size, xloc, yloc, tooltip, and text_font_family all have defaults that work out of the box.

▶How do I update a label after creating it in Pine Script?

Use the setter functions: label.set_text() to change the text, label.set_xy() to reposition it, label.set_color() to change the background, label.set_style() to switch shapes, and label.set_textcolor() to update text color. Declare the label with var so it persists across bars and can be updated efficiently instead of creating a new one each bar.

▶How do I display a number inside a label.new() in Pine Script?

Pine Script requires explicit type conversion. Use str.tostring(value) or str.tostring(value, "#.##") to convert numeric values to strings before passing them to the text parameter. For example: label.new(bar_index, high, "Price: " + str.tostring(close, "#.00")).

▶What label styles are available in Pine Script?

Pine Script provides directional callout styles (label.style_label_up, label.style_label_down, label.style_label_left, label.style_label_right), geometric shapes (label.style_circle, label.style_square, label.style_diamond), and arrow styles (label.style_arrowup, label.style_arrowdown). Pick the style based on whether you want to point toward the signal or simply mark a location.

▶How many labels can I create in a Pine Script indicator on TradingView?

The default display count is approximately 50 labels. You can raise max_labels_count up to 500 in the declaration. Garbage collection removes older labels beyond that configured count. Reuse a var label when only the latest value is needed.

▶What is the difference between label.new() and plotchar() in Pine Script?

label.new() creates a fully customizable callout with arbitrary text, tooltips, background color, and shape — ideal for displaying calculated values or multi-line annotations. plotchar() draws a single Unicode character at a fixed position and is simpler but can't display variable text or tooltips. Use label.new() when you need dynamic content; use plotchar() for simple signal markers.