Whatever message this page gives is out now! Go check it out!

SpreadsheetMergeCells

Last update:
May 18, 2026
Note:
You can find the CFFiddle demo of this function and other spreadsheet functions as part of a project that is shared with you.
Click the button below to launch CFFiddle.
To copy the project in your workspace in CFFiddle, follow the steps below:
  1. Log in with your Gmail or Facebook credentials.
  2. Navigate to the project in the left pane.
  3. Once you make some changes in any cfm in the project, a pop up displays asking you to save the project.
  4. Give the project a suitable name and click Save.

Description

Merges a rectangular block of two or more Excel spreadsheet object cells.

Returns

Nothing

Category

Spreadsheet functions, Microsoft Office integration functions

Syntax

SpreadsheetMergeCells (spreadsheetObj, startRow, endRow, startColumn, endColumn)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetGetCellValue, 
SpreadsheetSetCellComment, SpreadsheetSetCellFormula, SpreadsheetSetCellValue

History

ColdFusion 9: Added the function.

Parameters

Parameter
Description
spreadsheetObj
The Excel spreadsheet object containing the cells to merge.
startRow
The number of the first row to merge.
endRow
The row number of the last row to merge.
startColumn
The column number of the first cell to merge.
endColumn
The column number of the last cell to merge.

Usage

If you merge two cells using this function, the merged cell by default displays the value in the cell that is on the left-hand side of the spreadsheet. For example, if you merge the cell (20,3) and cell (20,4), then the value in the cell (20, 3) is displayed. If the cell (20, 3) is blank, then after merging, the cell displays blank.

Example

<cfscript>
       ArtOrders=QueryExecute("SELECT orderid,customerfirstname,customerlastname,address,total,city FROM orders
       ORDER BY orderid",[],{datasource="cfartgallery"});
       // Set the file path in the same location as this cfm
       myFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "myexcelfile.xlsx";
       // Create spreadsheet object. Set xml to true as this is an xlsx file
       mySheet=SpreadsheetNew("ColdFusion",true);
       // Set headers for the xlsx file
       SpreadSheetAddRow(mySheet,"Order,First Name,Last Name,Address,Amount,City");
       SpreadSheetAddRows(mySheet,ArtOrders);
 // Merge cells between rows 7-14 and cols 2-5
       SpreadsheetMergeCells(mySheet,7,14,2,5);
       SpreadsheetWrite(mySheet,"#myFile#",true);
</cfscript>

Output

Example

The following example merges cells 4-6 in rows 1-3 of an Excel spreadsheet object. It puts text in the merged cells and saves the sheet to a file so you can see the result.
///We need an absolute path, so get the current directory path.

theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "mergecells.xls";

//Create a new Excel spreadsheet object and add the query data.

theSheet = SpreadsheetNew("CourseData");

//Merges cells 4-6 in the first three rows of the Excel spreadsheet object.

SpreadsheetMergeCells(theSheet,1,3,4,6);

//Set the value of the merged cell.

SpreadsheetSetCellValue(theSheet,"Columns 4-6 of rows 1-3 are merged",1,4);

</cfscript>

<!--- Write the spreadsheet to a file, replacing any existing file. --->

<cfspreadsheet action="write" filename="#theFile#" name="theSheet" overwrite=true>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page