In Pine Script, the table.merge_cells()
function is a powerful tool for creating more dynamic and visually appealing tables within your trading indicators or strategies. This function allows you to merge a sequence of cells into one, creating a rectangle shape that spans from a specified top-left corner to a bottom-right corner. This feature is particularly useful for organizing and displaying grouped data or headings in a concise and readable format. Let’s dive into the syntax, arguments, and practical application of this function.
Syntax
The syntax for the table.merge_cells()
function is straightforward:
table.merge_cells(table_id, start_column, start_row, end_column, end_row) → void
This function does not return any value (void
) and operates directly on the table object specified by table_id
.
Arguments
- table_id (series table): This is the identifier of the table you’re working with. You must create a table object using
table.new()
before you can merge its cells. - start_column (series int): The column index of the top-left cell in the merge area, starting from 0.
- start_row (series int): The row index of the top-left cell in the merge area, starting from 0.
- end_column (series int): The column index of the bottom-right cell in the merge area, starting from 0.
- end_row (series int): The row index of the bottom-right cell in the merge area, starting from 0.
Example
Let’s consider an example that creates a table displaying three Simple Moving Averages (SMAs) for the last bar on the chart:
//@version=5 indicator("table.merge_cells example") SMA50 = ta.sma(close, 50) SMA150 = ta.sma(close, 150) SMA250 = ta.sma(close, 250) if barstate.islast maTable = table.new(position.bottom_right, 3, 3, bgcolor = color.gray, border_width = 1, border_color = color.black) // Header table.cell(maTable, 0, 0, text = "SMA Overview") table.merge_cells(maTable, 0, 0, 2, 0) // Cell Titles table.cell(maTable, 0, 1, text = "SMA 50") table.cell(maTable, 1, 1, text = "SMA 150") table.cell(maTable, 2, 1, text = "SMA 250") // Values table.cell(maTable, 0, 2, bgcolor = color.white, text = str.tostring(SMA50)) table.cell(maTable, 1, 2, bgcolor = color.white, text = str.tostring(SMA150)) table.cell(maTable, 2, 2, bgcolor = color.white, text = str.tostring(SMA250))

Walkthrough of Code
- Indicator Declaration:
- The script begins with
//@version=5
indicating it uses version 5 of Pine Script. indicator("table.merge_cells example")
declares a new indicator with the title “table.merge_cells example”.
- The script begins with
- Calculation of SMAs:
SMA50 = ta.sma(close, 50)
calculates the 50-period SMA of the closing prices.SMA150 = ta.sma(close, 150)
calculates the 150-period SMA of the closing prices.SMA250 = ta.sma(close, 250)
calculates the 250-period SMA of the closing prices.
- Conditional Execution:
if barstate.islast
ensures the following code block executes only on the last bar of the chart. This is typically used to avoid unnecessary calculations on every bar update.
- Table Creation:
maTable = table.new(position.bottom_right, 3, 3, bgcolor = color.gray, border_width = 1, border_color = color.black)
creates a new table positioned at the bottom right of the chart. This table has 3 columns and 3 rows, with a gray background, a border width of 1, and a black border color.
- Header Creation and Merging:
table.cell(maTable, 0, 0, text = "SMA Overview")
adds a cell with the text “SMA Overview” at the top-left corner (0,0) of the table.table.merge_cells(maTable, 0, 0, 2, 0)
merges the cells in the first row from the first column (0,0) to the third column (2,0) to create a single header cell spanning the entire width of the table.
- Adding Cell Titles:
- The script adds titles for each SMA value in the second row of the table:
table.cell(maTable, 0, 1, text = "SMA 50")
for the 50-period SMA.table.cell(maTable, 1, 1, text = "SMA 150")
for the 150-period SMA.table.cell(maTable, 2, 1, text = "SMA 250")
for the 250-period SMA.
- The script adds titles for each SMA value in the second row of the table:
- Displaying SMA Values:
- The script displays the calculated SMA values in the third row with a white background:
table.cell(maTable, 0, 2, bgcolor = color.white, text = str.tostring(SMA50))
shows the 50-period SMA value.table.cell(maTable, 1, 2, bgcolor = color.white, text = str.tostring(SMA150))
shows the 150-period SMA value.table.cell(maTable, 2, 2, bgcolor = color.white, text = str.tostring(SMA250))
shows the 250-period SMA value.
- The script displays the calculated SMA values in the third row with a white background:
Key Features and Takeaways
- Merging Capability: The function merges multiple cells into one larger cell, based on specified start and end points, enhancing table readability and organization.
- Inheritance of Properties: The merged cell inherits properties from the top-left cell, excluding width and height, which are automatically adjusted based on the merge.
- Modification Post-Merge: To modify a merged cell, use
table.cell_set_*
functions targeting the start cell’s coordinates. - Error Handling: Attempting to merge already merged cells will result in an error, ensuring data integrity and preventing script crashes.