prependColumns

function prependColumns(
  target: GoogleAppsScript.Spreadsheet.Sheet | GoogleAppsScript.Spreadsheet.Range,
  count: number,
  values?: unknown[][] | null,
  options: Options | null | undefined = {}
): GoogleAppsScript.Spreadsheet.Sheet;

Room is made first and the values are written into it, so nothing already on the sheet is overwritten. Given a sheet the columns go to its start; given a range they go before the range's first column and the values are written on its rows.

The matrix is indexed by row and then by column, and it has to be exactly count columns wide. Passing no values inserts empty columns.

A cell whose text starts with = is written as a formula, not as text — the same rule the editor follows.

Parameters

Parameter	Type	Description
`target`	`GoogleAppsScript.Spreadsheet.Sheet \\| GoogleAppsScript.Spreadsheet.Range`	The sheet to insert into, or the range to insert at.
`count`	`number`	How many columns to insert. `0` does nothing.
`values` (optional)	`unknown[][] \\| null`	A matrix indexed by row then column, exactly `count` columns wide. Omit it for empty columns.
`options` (optional) `= {}`	`Options \\| null \\| undefined`	`afterFrozenColumns` inserts after the frozen columns instead of at the very start. A range decides the position itself, so the option does nothing there.

Returns

GoogleAppsScript.Spreadsheet.Sheet — the sheet, so calls can be chained.

Throws

Exception	Condition
`IllegalArgumentException`	`count` is not a non-negative safe integer, or the values do not match it.
`InvalidSheetException`	the first argument is neither a sheet nor a range.

Examples

Inserting at the start of a sheet

const sheet = SpreadsheetApp.getActiveSheet();

prependColumns(sheet, 2, [
  ["A1", "B1"],
  ["A2", "B2"]
]);

Inserting at a range

const sheet = SpreadsheetApp.getActiveSheet();

prependColumns(sheet.getRange("C4:F13"), 1, [["note"]]);

Source

src/appsscript/sheet/prependColumns.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help