Google Apps Script

Class Sheet

Access and modify spreadsheet sheets. Common operations are renaming a sheet and accessing range objects from the sheet.

Methods

MethodReturn typeBrief description
activate()SheetActivates this sheet.
appendRow(rowContents)SheetAppends a row to the spreadsheet.
autoResizeColumn(columnPosition)SheetSets the width of the given column to fit its contents
clear()SheetClears the sheet of content and formatting information.
clear(options)SheetClears the sheet of contents and/or format, as specified with the given advanced options.
clearContents()SheetClears the sheet of contents, while preserving formatting information.
clearFormats()SheetClears the sheet of formatting, while preserving contents.
clearNotes()SheetClears the sheet of all notes.
copyTo(spreadsheet)SheetCopies the sheet to another spreadsheet.
deleteColumn(columnPosition)SheetDeletes the column at the given column position.
deleteColumns(columnPosition, howMany)voidDeletes a number of columns starting at the given column position.
deleteRow(rowPosition)SheetDeletes the row at the given row position.
deleteRows(rowPosition, howMany)voidDeletes a number of rows starting at the given row position.
getActiveCell()RangeReturns the active cell in this sheet.
getActiveRange()RangeReturns the active range for the active sheet.
getCharts()EmbeddedChart[]Returns an array of charts on this sheet.
getColumnWidth(columnPosition)IntegerGets the width in pixels of the given column.
getDataRange()RangeReturns a Range corresponding to the dimensions in which data is present.
getFrozenColumns()IntegerReturns the number of frozen columns.
getFrozenRows()IntegerReturns the number of frozen rows.
getIndex()IntegerGets the position of the sheet in its parent spreadsheet.
getLastColumn()IntegerReturns the position of the last column that has content.
getLastRow()IntegerReturns the position of the last row that has content.
getMaxColumns()IntegerThe maximum width of the sheet, regardless of content.
getMaxRows()IntegerThe maximum height of the sheet, regardless of content.
getName()StringReturns the name of the sheet.
getParent()SpreadsheetReturns the Spreadsheet that contains this sheet.
getRange(row, column)RangeReturns the range with the top left cell at the given coordinates.
getRange(row, column, numRows)RangeReturns the range with the top left cell at the given coordinates, and with the given number of rows.
getRange(row, column, numRows, numColumns)RangeReturns the range with the top left cell at the given coordinates with the given number of rows and columns.
getRange(a1Notation)RangeReturns the range as specified in A1 notation or R1C1 notation.
getRowHeight(rowPosition)IntegerGets the height in pixels of the given row.
getSheetId()IntegerReturns the ID of the sheet represented by this object.
getSheetName()StringReturns the sheet name.
getSheetProtection()PageProtectionReturns a PageProtection instance describing the permissions for the current sheet.
getSheetValues(startRow, startColumn, numRows, numColumns)Object[][]Returns the rectangular grid of values for this range starting at the given coordinates.
hideColumn(column)voidHides the columns in the given range.
hideColumns(columnIndex)voidHides the column at the given index.
hideColumns(columnIndex, numColumns)voidHides one or more consecutive columns starting at the given index.
hideRow(row)voidHides the rows in the given range.
hideRows(rowIndex)voidHides the row at the given index.
hideRows(rowIndex, numRows)voidHides one or more consecutive rows starting at the given index.
hideSheet()SheetHides this sheet.
insertChart(chart)voidAdds a new chart to this sheet.
insertColumnAfter(afterPosition)SheetInserts a column after the given column position.
insertColumnBefore(beforePosition)SheetInserts a column before the given column position.
insertColumns(columnIndex)voidInserts a blank column in a sheet at the specified location.
insertColumns(columnIndex, numColumns)voidInserts one or more consecutive blank columns in a sheet starting at the specified location.
insertColumnsAfter(afterPosition, howMany)SheetInserts a number of columns after the given column position.
insertColumnsBefore(beforePosition, howMany)SheetInserts a number of columns before the given column position.
insertImage(url, column, row)voidInserts an image in the document at a given row and column.
insertImage(url, column, row, offsetX, offsetY)voidInserts an image in the document at a given row and column with a pixel offset.
insertRowAfter(afterPosition)SheetInserts a row after the given row position.
insertRowBefore(beforePosition)SheetInserts a row before the given row position.
insertRows(rowIndex)voidInserts a blank row in a sheet at the specified location.
insertRows(rowIndex, numRows)voidInserts one or more consecutive blank rows in a sheet starting at the specified location.
insertRowsAfter(afterPosition, howMany)SheetInserts a number of rows after the given row position.
insertRowsBefore(beforePosition, howMany)SheetInserts a number of rows before the given row position.
isSheetHidden()BooleanReturns true if the sheet is currently hidden.
newChart()EmbeddedChartBuilderReturns a builder to create a new chart for this sheet.
removeChart(chart)voidRemoves a chart from the parent sheet.
setActiveRange(range)RangeSets the active range for the active sheet.
setActiveSelection(range)RangeSets the active selection region for this sheet.
setActiveSelection(a1Notation)RangeSets the active selection, as specified in A1 notation or R1C1 notation.
setColumnWidth(columnPosition, width)SheetSets the width of the given column in pixels.
setFrozenColumns(columns)voidFreezes the given number of columns.
setFrozenRows(rows)voidFreezes the given number of rows.
setName(name)SheetSets the sheet name.
setRowHeight(rowPosition, height)SheetSets the row height of the given row in pixels.
setSheetProtection(permissions)voidSets the permissions for the current sheet.
showColumns(columnIndex)voidUnhides the column at the given index.
showColumns(columnIndex, numColumns)voidUnhides one or more consecutive columns starting at the given index.
showRows(rowIndex)voidUnhides the row at the given index.
showRows(rowIndex, numRows)voidUnhides one or more consecutive rows starting at the given index.
showSheet()SheetMakes the sheet visible.
sort(columnPosition)SheetSorts a sheet by column, ascending.
sort(columnPosition, ascending)SheetSorts a sheet by column.
unhideColumn(column)voidUnhides the column in the given range.
unhideRow(row)voidUnhides the row in the given range.
updateChart(chart)voidUpdates the chart on this sheet.

Detailed documentation

activate()

Activates this sheet. Does not alter the sheet itself, only the parent's notion of the active sheet.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.activate();
 

Return

Sheet — the newly active sheet


appendRow(rowContents)

Appends a row to the spreadsheet. This operation is atomic; it prevents issues where a user asks for the last row, and then writes to that row, and an intervening mutation occurs between getting the last row and writing to it.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Appends a new row with 3 columns to the bottom of the
 // spreadsheet containing the values in the array
 sheet.appendRow(["a man", "a plan", "panama"]);
 

Parameters

NameTypeDescription
rowContentsObject[]an array of values to insert after the last row in the sheet

Return

Sheet — the sheet, useful for method chaining


autoResizeColumn(columnPosition)

Sets the width of the given column to fit its contents

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 sheet.getRange('a1').setValue('Whenever it is a damp, drizzly November in my soul...');

 // Sets the first column to a width which fits the text
 sheet.autoResizeColumn(1);
 

Parameters

NameTypeDescription
columnPositionIntegerthe position of the given column to resize

Return

Sheet — the sheet, useful for method chaining


clear()

Clears the sheet of content and formatting information.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.clear();
 

Return

Sheet — the cleared sheet


clear(options)

Clears the sheet of contents and/or format, as specified with the given advanced options. The advanced options are:

  • contentsOnly
  • formatOnly
 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 sheet.clear({ formatOnly: true, contentsOnly: true });
 

Parameters

NameTypeDescription
optionsObjecta JavaScript map containining advanced options

Return

Sheet — the sheet for chaining


clearContents()

Clears the sheet of contents, while preserving formatting information.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.clearContents();
 

Return

Sheet — the sheet for chaining


clearFormats()

Clears the sheet of formatting, while preserving contents. Formatting refers to how data is formatted as allowed by choices under the "Format" menu (ex: bold, italics, conditional formatting) and not width or height of cells.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.clearFormats();
 

Return

Sheet — the sheet for chaining


clearNotes()

Clears the sheet of all notes.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.clearNotes();
 

Return

Sheet — the sheet for chaining


copyTo(spreadsheet)

Copies the sheet to another spreadsheet. The destination spreadsheet can be the source. The new spreadsheet will have the name "Copy of [original spreadsheet name]".

 
var source = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = source.getSheets()[0];

 var destination = SpreadsheetApp.openById("ID_GOES HERE");
 sheet.copyTo(destination);
 

Parameters

NameTypeDescription
spreadsheetSpreadsheeta destination spreadsheet to copy this sheet to

Return

Sheet — the copied sheet for chaining


deleteColumn(columnPosition)

Deletes the column at the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Columns start at "1" - this will delete the first column
 sheet.deleteColumn(1);
 

Parameters

NameTypeDescription
columnPositionIntegerthe position of the column, starting at 1 for the first column

Return

Sheet — the sheet, useful for method chaining


deleteColumns(columnPosition, howMany)

Deletes a number of columns starting at the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Columns start at "1" - this will delete the first two columns
 sheet.deleteColumns(1, 2);
 

Parameters

NameTypeDescription
columnPositionIntegerthe position of the first column to delete
howManyIntegerthe number of columns to delete

deleteRow(rowPosition)

Deletes the row at the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Rows start at "1" - this will delete the first row
 sheet.deleteRow(1);
 

Parameters

NameTypeDescription
rowPositionIntegerthe position of the row, starting at 1 for the first row

Return

Sheet — the sheet, useful for method chaining


deleteRows(rowPosition, howMany)

Deletes a number of rows starting at the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Rows start at "1" - this will delete the first two rows
 sheet.deleteRows(1, 2);
 

Parameters

NameTypeDescription
rowPositionIntegerthe position of the first row to delete
howManyIntegerthe number of rows to delete

getActiveCell()

Returns the active cell in this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Returns the active cell
 var cell = sheet.getActiveCell();
 

Return

Range — the current active cell


getActiveRange()

Returns the active range for the active sheet. Returns the range of cells that is currently considered active. This generally means the range that a user has selected in the active sheet, but in a custom function it refers to the cell being actively recalculated. Note that when called on a SpreadsheetApp it effectively calls getActiveSpreadsheet and then getActiveSheet to act on the active Sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Returns the active cell
 var range = sheet.getActiveRange();
 

Return

Range — the active range

See also


getCharts()

Returns an array of charts on this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 var charts = sheet.getCharts();

 for (var i in charts) {
   var chart = charts[i];
   // Do something with the chart
 }
 

Return

EmbeddedChart[] — an array of charts


getColumnWidth(columnPosition)

Gets the width in pixels of the given column.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Columns start at 1
 Logger.log(sheet.getColumnWidth(1));
 

Parameters

NameTypeDescription
columnPositionIntegerthe position of the column to examine

Return

Integer — column width in pixels


getDataRange()

Returns a Range corresponding to the dimensions in which data is present. This is functionally equivalent to creating a Range bounded by A1 and (Range.getLastColumn(), Range.getLastRow()).

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This represents ALL the data
 var range = sheet.getDataRange();
 var values = range.getValues();

 // This logs the spreadsheet in CSV format with a trailing comma
 for (var i = 0; i < values.length; i++) {
   var row = "";
   for (var j = 0; j < values[i].length; j++) {
     if (values[i][j]) {
       row = row + values[i][j];
     }
     row = row + ",";
   }
   Logger.log(row);
 }
 

Return

Range — a range consisting of all the data in the spreadsheet


getFrozenColumns()

Returns the number of frozen columns.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 Logger.log("Number of frozen columns: %s", sheet.getFrozenColumns());
 

Return

Integer — the number of frozen columns


getFrozenRows()

Returns the number of frozen rows.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 Logger.log("Number of frozen rows: %s", sheet.getFrozenRows());
 

Return

Integer — the number of frozen rows


getIndex()

Gets the position of the sheet in its parent spreadsheet. Starts at 1.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 // Note that the JavaScript index is 0, but this will log 1
 var sheet = ss.getSheets()[0];
 // ... because spreadsheets are 1-indexed
 Logger.log(sheet.getIndex());
 

Return

Integer — the position of the sheet in its parent spreadsheet


getLastColumn()

Returns the position of the last column that has content.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This logs the value in the very last cell of this sheet
 var lastRow = sheet.getLastRow();
 var lastColumn = sheet.getLastColumn();
 var lastCell = sheet.getRange(lastRow, lastColumn);
 Logger.log(lastCell.getValue());
 

Return

Integer — the last column of the sheet that contains content


getLastRow()

Returns the position of the last row that has content.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This logs the value in the very last cell of this sheet
 var lastRow = sheet.getLastRow();
 var lastColumn = sheet.getLastColumn();
 var lastCell = sheet.getRange(lastRow, lastColumn);
 Logger.log(lastCell.getValue());
 

Return

Integer — the last row of the sheet that contains content


getMaxColumns()

The maximum width of the sheet, regardless of content.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 Logger.log(first.getMaxColumns());
 

Return

Integer — the maximum width of the sheet


getMaxRows()

The maximum height of the sheet, regardless of content.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 Logger.log(first.getMaxRows());
 

Return

Integer — the maximum height of the sheet


getName()

Returns the name of the sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 Logger.log(sheet.getName());
 

Return

String — the name of the sheet


getParent()

Returns the Spreadsheet that contains this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // parent is identical to ss
 var parent = sheet.getParent();
 

Return

Spreadsheet — the parent spreadsheet


getRange(row, column)

Returns the range with the top left cell at the given coordinates.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Passing only two arguments returns a "range" with a single cell.
 var range = sheet.getRange(1, 1);
 var values = range.getValues();
 Logger.log(values[0][0]);
 

Parameters

NameTypeDescription
rowIntegerthe row of the cell to return
columnIntegerthe column of the cell to return

Return

Range — a Range containing only this cell


getRange(row, column, numRows)

Returns the range with the top left cell at the given coordinates, and with the given number of rows.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // When the "numRows" argument is used, only a single column of data is returned.
 var range = sheet.getRange(1, 1, 3);
 var values = range.getValues();

 // Prints 3 values from the first column, starting from row 1.
 for (var row in values) {
   for (var col in values[row]) {
     Logger.log(values[row][col]);
   }
 }
 

Parameters

NameTypeDescription
rowIntegerthe starting row of the range
columnIntegerthe column of the range
numRowsIntegerthe number of rows to return

Return

Range — a Range containing a single column of data with the number of rows specified


getRange(row, column, numRows, numColumns)

Returns the range with the top left cell at the given coordinates with the given number of rows and columns.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 var range = sheet.getRange(1, 1, 3, 3);
 var values = range.getValues();

 // Print values from a 3x3 box.
 for (var row in values) {
   for (var col in values[row]) {
     Logger.log(values[row][col]);
   }
 }
 

Parameters

NameTypeDescription
rowIntegerthe starting row of the range
columnIntegerthe starting column of the range
numRowsIntegerthe number of rows to return
numColumnsIntegerthe number of columns to return

Return

Range — a Range corresponding to the area specified


getRange(a1Notation)

Returns the range as specified in A1 notation or R1C1 notation.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Returns the first cell
 var cell = sheet.getRange("A1");
 

Parameters

NameTypeDescription
a1NotationStringthe range to return, as specified in A1 notation or R1C1 notation

Return

Range — the range at the location designated


getRowHeight(rowPosition)

Gets the height in pixels of the given row.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Rows start at 1
 Logger.log(sheet.getRowHeight(1));
 

Parameters

NameTypeDescription
rowPositionIntegerthe *position* of the row to examine

Return

Integer — row height in pixels


getSheetId()

Returns the ID of the sheet represented by this object. This is an ID for the sheet that is unique to the spreadsheet. The ID is a monotonically increasing integer assigned at sheet creation time that is independent of sheet position. This is useful in conjunction with methods such as Range.copyFormatToRange(gridId, column, columnEnd, row, rowEnd) that take a gridId parameter rather than a Sheet instance.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 Logger.log(sheet.getSheetId());
 

Return

Integer — an ID for the sheet unique to the spreadsheet


getSheetName()

Returns the sheet name.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 Logger.log(sheet.getSheetName());
 

Return

String — the name of the sheet


getSheetProtection()

Returns a PageProtection instance describing the permissions for the current sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var permissions = sheet.getSheetProtection();

 permissions.setProtected(true);
 permissions.addUser("user@example.com");

 // Logs the users that have access to edit this sheet. Note that this
 // is different from access to the entire spreadsheet - getUsers() will
 // only return users if permissions.isProtected() is set to true.
 var users = permissions.getUsers();
 Logger.log(users);
 

Return

PageProtection — an object describing sheet access permissions


getSheetValues(startRow, startColumn, numRows, numColumns)

Returns the rectangular grid of values for this range starting at the given coordinates. A -1 value given as the row or column position is equivalent to getting the very last row or column that has data in the sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // The two samples below produce the same output
 var values = sheet.getSheetValues(1, 1, 3, 3);
 Logger.log(values);

 var range = sheet.getRange(1, 1, 3, 3);
 values = range.getValues();
 Logger.log(values);
 

Parameters

NameTypeDescription
startRowIntegerthe position of the starting row
startColumnIntegerthe position of the starting column
numRowsIntegerthe number of rows to return values for
numColumnsIntegerthe number of columns to return values for

Return

Object[][] — a two dimension array of values


hideColumn(column)

Hides the columns in the given range.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This hides the first column
 var range = sheet.getRange("A1");
 sheet.hideColumn(range);
 

Parameters

NameTypeDescription
columnRangethe column range to hide

hideColumns(columnIndex)

Hides the column at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Hides the first column
 sheet.hideColumns(1);
 

Parameters

NameTypeDescription
columnIndexIntegerthe index of the column to hide

hideColumns(columnIndex, numColumns)

Hides one or more consecutive columns starting at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Hides the first three columns
 sheet.hideColumns(1, 3);
 

Parameters

NameTypeDescription
columnIndexIntegerthe starting index of the columns to hide
numColumnsIntegerthe number of columns to hide

hideRow(row)

Hides the rows in the given range.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This hides the first row
 var range = sheet.getRange("A1");
 sheet.hideRow(range);
 

Parameters

NameTypeDescription
rowRangethe row range to hide

hideRows(rowIndex)

Hides the row at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Hides the first row
 sheet.hideRows(1);
 

Parameters

NameTypeDescription
rowIndexIntegerthe index of the row to hide

hideRows(rowIndex, numRows)

Hides one or more consecutive rows starting at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Hides the first three rows
 sheet.hideRows(1, 3);
 

Parameters

NameTypeDescription
rowIndexIntegerthe starting index of the rows to hide
numRowsIntegerthe number of rows to hide

hideSheet()

Hides this sheet. Has no effect if the sheet is already hidden. If this method is called on the only visible sheet, it will throw an exception.

 
var sheet = SpreadsheetApp.getActiveSheet();
 sheet.hideSheet();
 

Return

Sheet — the current sheet


insertChart(chart)

Adds a new chart to this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This creates a simple bar chart from the first three rows
 // of the first two columns of the spreadsheet
 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(sheet.getRange("A1:B4"))
     .setPosition(5, 5, 0, 0)
     .setOption("title", "Dynamic Chart")
     .build();
 sheet.insertChart(chart);
 

Parameters

NameTypeDescription
chartEmbeddedChartthe chart to insert

insertColumnAfter(afterPosition)

Inserts a column after the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts a column after the first column position
 sheet.insertColumnAfter(1);
 

Parameters

NameTypeDescription
afterPositionIntegerthe column after which the new column should be added

Return

Sheet — the sheet, useful for method chaining


insertColumnBefore(beforePosition)

Inserts a column before the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts a column in the first column position
 sheet.insertColumnBefore(1);
 

Parameters

NameTypeDescription
beforePositionIntegerthe column before which the new column should be added

Return

Sheet — the sheet, useful for method chaining


insertColumns(columnIndex)

Inserts a blank column in a sheet at the specified location.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Shifts all columns by one
 sheet.insertColumns(1);
 

Parameters

NameTypeDescription
columnIndexIntegerthe index to insert a column

insertColumns(columnIndex, numColumns)

Inserts one or more consecutive blank columns in a sheet starting at the specified location.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Shifts all columns by three
 sheet.insertColumns(1, 3);
 

Parameters

NameTypeDescription
columnIndexIntegerthe index to insert a column
numColumnsIntegerthe number of columns to insert

insertColumnsAfter(afterPosition, howMany)

Inserts a number of columns after the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts a column in the second column position
 sheet.insertColumnsAfter(1);
 

Parameters

NameTypeDescription
afterPositionIntegerthe column after which the new column should be added
howManyIntegerthe number of columns to insert

Return

Sheet — the sheet, useful for method chaining


insertColumnsBefore(beforePosition, howMany)

Inserts a number of columns before the given column position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts five columns before the first column
 sheet.insertColumnsBefore(1, 5);
 

Parameters

NameTypeDescription
beforePositionIntegerthe column before which the new column should be added
howManyIntegerthe number of columns to insert

Return

Sheet — the sheet, useful for method chaining


insertImage(url, column, row)

Inserts an image in the document at a given row and column.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1);
 

Parameters

NameTypeDescription
urlStringthe url of the image
columnIntegerthe grid column position
rowIntegerthe grid row position

insertImage(url, column, row, offsetX, offsetY)

Inserts an image in the document at a given row and column with a pixel offset.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1, 10, 10);
 

Parameters

NameTypeDescription
urlStringthe url for the image
columnIntegerthe column position
rowIntegerthe row position
offsetXIntegerhorizontal offset from cell corner in pixels
offsetYIntegervertical offset from cell corner in pixels

insertRowAfter(afterPosition)

Inserts a row after the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts a row after the first row position
 sheet.insertRowAfter(1);
 

Parameters

NameTypeDescription
afterPositionIntegerthe row after which the new row should be added

Return

Sheet — the sheet, useful for method chaining


insertRowBefore(beforePosition)

Inserts a row before the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts a row before the first row position
 sheet.insertRowBefore(1);
 

Parameters

NameTypeDescription
beforePositionIntegerthe row before which the new row should be added

Return

Sheet — the sheet, useful for method chaining


insertRows(rowIndex)

Inserts a blank row in a sheet at the specified location.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Shifts all rows down by one
 sheet.insertRows(1);
 

Parameters

NameTypeDescription
rowIndexIntegerthe index to insert a row

insertRows(rowIndex, numRows)

Inserts one or more consecutive blank rows in a sheet starting at the specified location.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Shifts all rows down by three
 sheet.insertRows(1, 3);
 

Parameters

NameTypeDescription
rowIndexIntegerthe index to insert a row
numRowsIntegerthe number of rows to insert

insertRowsAfter(afterPosition, howMany)

Inserts a number of rows after the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts five rows after the first row
 sheet.insertRowsAfter(1, 5);
 

Parameters

NameTypeDescription
afterPositionIntegerthe row after which the new rows should be added
howManyIntegerthe number of rows to insert

Return

Sheet — the sheet, useful for method chaining


insertRowsBefore(beforePosition, howMany)

Inserts a number of rows before the given row position.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This inserts five rows before the first row
 sheet.insertRowsBefore(1, 5);
 

Parameters

NameTypeDescription
beforePositionIntegerthe row before which the new rows should be added
howManyIntegerthe number of rows to insert

Return

Sheet — the sheet, useful for method chaining


isSheetHidden()

Returns true if the sheet is currently hidden.

 
var sheet = SpreadsheetApp.getActiveSheet();
 if (sheet.isSheetHidden()) {
   // do something...
 }
 

Return

Boolean — true if the sheet is hidden, false otherwise


newChart()

Returns a builder to create a new chart for this sheet.

This example shows how to create a new chart:

 
var sheet = SpreadsheetApp.getActiveSheet();
 var range = sheet.getRange("A1:B8");
 var chartBuilder = sheet.newChart();
 chartBuilder.addRange(range)
     .setChartType(Charts.ChartType.Line)
     .setPosition(2, 2, 0, 0)
     .setOption('title', 'My Line Chart!');
 sheet.insertChart(chartBuilder.build());
 

Return

EmbeddedChartBuilder — a builder for create a new chart


removeChart(chart)

Removes a chart from the parent sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This removes all the embedded charts from the spreadsheet
 var charts = sheet.getCharts();
 for (var i in charts) {
   sheet.removeChart(charts[i]);
 }
 

Parameters

NameTypeDescription
chartEmbeddedChartthe chart to remove

setActiveRange(range)

Sets the active range for the active sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:D4");
 sheet.setActiveRange(range);
 

Parameters

NameTypeDescription
rangeRangethe range to set as the active range

Return

Range — the newly active range


setActiveSelection(range)

Sets the active selection region for this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:D4");
 sheet.setActiveSelection(range);
 

Parameters

NameTypeDescription
rangeRangethe range to set as the active selection

Return

Range — the newly active range


setActiveSelection(a1Notation)

Sets the active selection, as specified in A1 notation or R1C1 notation.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 sheet.setActiveSelection("A1:D4");
 

Parameters

NameTypeDescription
a1NotationStringthe range to set as active, as specified in A1 notation or R1C1 notation

Return

Range — the newly active range


setColumnWidth(columnPosition, width)

Sets the width of the given column in pixels.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Sets the first column to a width of 200 pixels
 sheet.setColumnWidth(1, 200);
 

Parameters

NameTypeDescription
columnPositionIntegerthe position of the given column to set
widthIntegerthe width in pixels to set it to

Return

Sheet — the sheet, useful for method chaining


setFrozenColumns(columns)

Freezes the given number of columns. If zero, no columns are frozen.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Freezes the first column
 sheet.setFrozenColumns(1);
 

Parameters

NameTypeDescription
columnsIntegerthe number of columns to freeze

setFrozenRows(rows)

Freezes the given number of rows. If zero, no rows are frozen.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 Freezes the first row
 sheet.setFrozenRows(1);
 

Parameters

NameTypeDescription
rowsIntegerthe number of rows to freeze

setName(name)

Sets the sheet name.

 
// This example assumes there is a sheet named "first"
 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var first = ss.getSheetByName("first");
 first.setName("not first anymore");
 

Parameters

NameTypeDescription
nameStringthe new name for the sheet

Return

Sheet — the sheet for chaining


setRowHeight(rowPosition, height)

Sets the row height of the given row in pixels.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Sets the first row to a height of 200 pixels
 sheet.setRowHeight(1, 200);
 

Parameters

NameTypeDescription
rowPositionIntegerthe row position to change
heightIntegerheight in pixels to set it to

Return

Sheet — the sheet, useful for method chaining


setSheetProtection(permissions)

Sets the permissions for the current sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var permissions = sheet.getSheetProtection();

 // This copies the permissions on the first sheet to the second sheet
 var sheetToClonePermissionsTo = ss.getSheets()[1];
 sheetToClonePermissionsTo.setSheetProtection(permissions);
 

Parameters

NameTypeDescription
permissionsPageProtectionthe access permissions object to set on this sheet

showColumns(columnIndex)

Unhides the column at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Unhides the first column
 sheet.showColumns(1);
 

Parameters

NameTypeDescription
columnIndexIntegerthe index of the column to unhide

showColumns(columnIndex, numColumns)

Unhides one or more consecutive columns starting at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Unhides the first three columns
 sheet.showColumns(1, 3);
 

Parameters

NameTypeDescription
columnIndexIntegerthe starting index of the columns to unhide
numColumnsIntegerthe number of columns to unhide

showRows(rowIndex)

Unhides the row at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Unhides the first row
 sheet.showRows(1);
 

Parameters

NameTypeDescription
rowIndexIntegerthe index of the row to unhide

showRows(rowIndex, numRows)

Unhides one or more consecutive rows starting at the given index.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];
 // Unhides the first three rows
 sheet.showRows(1, 3);
 

Parameters

NameTypeDescription
rowIndexIntegerthe starting index of the rows to unhide
numRowsIntegerthe number of rows to unhide

showSheet()

Makes the sheet visible. Has no effect if the sheet is already visible.

 
var sheet = SpreadsheetApp.getActiveSheet();
 sheet.showSheet();
 

Return

Sheet — the current sheet


sort(columnPosition)

Sorts a sheet by column, ascending.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Sorts the sheet by the first column, ascending
 sheet.sort(1);
 

Parameters

NameTypeDescription
columnPositionIntegerthe column to sort by

Return

Sheet — the sheet, useful for method chaining


sort(columnPosition, ascending)

Sorts a sheet by column. Takes a parameter to specify ascending or descending.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // Sorts the sheet by the first column, descending
 sheet.sort(1, false);
 

Parameters

NameTypeDescription
columnPositionIntegerthe column to sort by
ascendingBooleantrue for ascending, false for descending

Return

Sheet — the sheet, useful for method chaining


unhideColumn(column)

Unhides the column in the given range.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This unhides the first column if it was previously hidden
 var range = sheet.getRange("A1");
 sheet.unhideColumn(range);
 

Parameters

NameTypeDescription
columnRangethe range to unhide, if hidden

unhideRow(row)

Unhides the row in the given range.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This unhides the first row if it was previously hidden
 var range = sheet.getRange("A1");
 sheet.unhideRow(range);
 

Parameters

NameTypeDescription
rowRangethe range to unhide, if hidden

updateChart(chart)

Updates the chart on this sheet.

 
var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 // This code is going to loop through all the charts and change them to
 // column charts
 var charts = sheet.getCharts();
 for (var i in charts) {
   var chart = charts[i];
   var newChart = chart
       .modify()
       .setChartType(Charts.ChartType.COLUMN)
       .build();
   sheet.updateChart(newChart);
 }
 

Parameters

NameTypeDescription
chartEmbeddedChartthe chart to update

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.