Label.new Function in Pine Script

Among Many pinescript functions, label.new plays a crucial role. It’s used to create a new label object on the chart for better visualization. In this tutorial, we’ll break down how to use this function effectively in your scripts.

Defining label.new

label.new is a function that generates a new label object. It uses a set of parameters to define the properties of the label, such as its position, color, text, and style. The basic syntax of the function is as follows:

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

Parameters of label.new

Let’s delve into each argument this function accepts:

x (series int): This parameter denotes the bar index or UNIX time of the label position, depending on whether xloc is set to xloc.bar_index or xloc.bar_time.
y (series int/float): It represents the price position of the label. It is taken into account only if yloc=yloc.price.
text (series string): This parameter is used to set the label’s text.
text_font_family (series string): It sets the font family of the text. The default value is font.family_default.
xloc (series string): This parameter determines the x-coordinate of the label position. The default is xloc.bar_index.
yloc (series string): It is used to set the y-coordinate of the label position. The default is yloc.price.
color (series color): This parameter sets the color of the label border and arrow.
style (series string): This parameter is used to set the label style.
textcolor (series color): It sets the color of the label text.
size (series string): This parameter sets the label size.
textalign (series string): It is used to align the label text.
tooltip (series string): It sets the tooltip label that appears on hover.

Returns

The function returns a Label ID object which may be passed to label.setXXX and label.getXXX functions for further modifications and retrievals.

Unique Use Case: Tracking the Highest High of the Last 10 Bars

Let’s walk through a simple script that creates a label on the highest high of the last 10 bars. The script will update the label’s position whenever a new highest high is achieved.

//@version=5
indicator("Highest High Label Tracker", overlay = true)
highestHigh = ta.highest(high, 10)
var hiLabel = label.new(na, na, "Highest High", xloc = xloc.bar_index, yloc = yloc.price, color=color.green, style=label.style_label_down)
if (high == highestHigh)
    label.set_xy(hiLabel, bar_index, highestHigh)
    label.set_text(hiLabel, "Highest High: " + tostring(highestHigh))

Here’s a breakdown of the script:

The script initializes by using the indicator function to set up the script properties.
We use ta.highest(high, 10) to determine the highest high over the last 10 bars.
A new label (hiLabel) is created, but with na values for x and y coordinates. This is because the exact position will be determined in the following logic.
In the condition if (high == highestHigh), we check if the current bar’s high is equal to the highest high of the last 10 bars. If true, the label is moved to this new high using label.set_xy. The label’s text is also updated with the new highest high value using label.set_text.

This script can be beneficial for traders who are monitoring specific price levels for breakout or reversal.

Key Takeaways

Understanding how to use the label.new function in Pine Script can significantly improve the usability and readability of your custom scripts. By being able to create and manipulate labels on the chart, you can provide clear and direct visual cues to supplement your trading strategies. Remember, a well-organized and insightful chart can greatly enhance your decision-making process in trading.

Conclusion

With label.new and its accompanying functions, Pine Script provides a flexible and efficient way to add custom labels to your charts. By mastering these, you can create powerful visual aids to assist in your trading strategy. Happy coding!