Box.new Function in Pine Script

Pine Script is a domain-specific language for coding custom technical analysis indicators, strategies, and alerts on the TradingView platform. In this tutorial, we will take a closer look at one of the key functions in Pine Script: box.new.

Understanding box.new Function

The box.new function is used to create a new box object on the chart. The function takes several parameters that define the characteristics of the box, such as its borders, color, text, and alignment.

Below is the syntax for the box.new function:

box.new(left, top, right, bottom, border_color, border_width, border_style, extend, xloc, bgcolor, text, text_size, text_color, text_halign, text_valign, text_wrap, text_font_family) → series box

Arguments of box.new Function

Each argument of the box.new function controls a specific aspect of the box object.

Box Coordinates

left and right (series int)

These parameters define the horizontal position of the box. They can be a bar index or a UNIX timestamp, depending on the xloc argument.

top and bottom (series int/float)

These parameters define the vertical position of the box, indicating the price levels for the top and bottom borders.

Box Appearance

border_color, border_width, border_style

These arguments control the appearance of the box borders. You can define the color, width (in pixels), and style (solid, dotted, or dashed) of the box borders.

bgcolor

This argument sets the background color of the box.

Box Text

text, text_size, text_color, text_halign, text_valign, text_wrap, text_font_family

These arguments control the text displayed inside the box. You can specify the text, its size, color, horizontal and vertical alignment, wrapping, and font family.

Example: Using the box.new Function

Let’s delve into an example to understand how we can use the box.new function:

//@version=5
indicator(title="Extended Box Example", overlay=true)

// Create persistent variable to track the box identifier
var box previousDayBox = na

// Check if a new trading day has started
if dayofmonth != dayofmonth[1]
    // Create a purple box that extends to the right
    previousDayBox := box.new(left=bar_index, top=high,
         right=bar_index + 1, bottom=low,
         bgcolor=color.new(#9b27b0, 0),
         border_width=0, extend=extend.right)
    
    // To prevent clutter, disable extension
    // from the previous day's box
    box.set_extend(id=previousDayBox[1], extend=extend.none)
    box.delete(previousDayBox[1])

In the above script:

1. var box previousDayBox = na: This line declares a persistent variable previousDayBox to store the identifier (id) of the box object created for each day. The na function is used to initialize it with a “not a number” value since we have no box object yet.
2. if dayofmonth != dayofmonth[1]: This line checks if the current bar is the first bar of a new day. dayofmonth returns the day of the month for the current bar, while dayofmonth[1] returns the day of the month for the previous bar. If these two values differ, it means a new day has begun.
3. previousDayBox := box.new(…): This line creates a new box object for the new day with certain characteristics:
   • left=bar_index: The left border of the box is at the current bar index.
   • top=high: The top border of the box is at the high price of the current bar.
   • right=bar_index + 1: The right border of the box is one bar after the current bar.
   • bottom=low: The bottom border of the box is at the low price of the current bar.
   • bgcolor=color.new(#9b27b0, 0): The background color of the box is set to a fully transparent purple (#9b27b0), effectively making it invisible.
   • border_width=0: The border width of the box is set to 0, making the border invisible.
   • extend=extend.right: The box extends indefinitely to the right.
4. box.set_extend(id=previousDayBox[1], extend=extend.none): This line disables the rightward extension of the box from the previous day. The box.set_extend function modifies the extend attribute of a box object. id=previousDayBox[1] specifies the id of the box to modify (the box from the previous day), and extend=extend.none sets the box’s extension to none, preventing it from extending further.

This script will create a new, invisible box for each trading day and extend it to the right. This might seem pointless since the boxes are invisible, but the boxes could be used for calculations or other operations. At the start of each new day, the script also stops the previous day’s box from extending further to the right.

Key Takeaway

The box.new function is a powerful tool in Pine Script that allows you to create custom box objects on your TradingView charts. By understanding the function arguments and how to use them, you can customize boxes to highlight specific areas on the chart, enhance your visual analysis, or add custom annotations.

Conclusion

The box.new function offers an extensive range of customization for highlighting certain aspects or areas of your charts in Pine Script. By understanding the functionalities of each argument, you can create a box that perfectly suits your trading strategy or analysis. Whether it’s for marking significant events, outlining price ranges, or even providing custom annotations and notes, box.new is a powerful function that can significantly enhance your charting experience on TradingView.