clearRowsByConditional

function clearRowsByConditional(
  target: GoogleAppsScript.Spreadsheet.Sheet | GoogleAppsScript.Spreadsheet.Range,
  predicate: RowPredicate,
  options: RowConditionalOptions | null | undefined = {}
): number;

The contents go and the rows stay, so positions do not shift and anything referring to a row by its number keeps pointing at the same place. deleteRowsByConditional is the one that removes them.

The sheet is read once and the clearing is grouped into consecutive blocks, so a scattered selection still costs few calls to the service.

A sheet means its whole data range; a range means only the cells inside it, with the rest of the sheet neither read nor touched. Either way the predicate is given the position on the sheet, so a row keeps its real number.

Parameters

Parameter	Type	Description
`target`	`GoogleAppsScript.Spreadsheet.Sheet \\| GoogleAppsScript.Spreadsheet.Range`	The sheet to work on, or the range to work within: only its cells are read, and only they are cleared.
`predicate`	`RowPredicate`	Receives the row's cells, its one-based position and — when `headerRow` is set — the row keyed by the column names. Return `true` for the rows to act on.
`options` (optional) `= {}`	`RowConditionalOptions \\| null \\| undefined`	`headerRow` names the row holding the column names. Setting it keys each row by those names and keeps the header row itself out of the candidates.

Returns

number — how many were affected.

Throws

Exception	Condition
`InvalidSheetException`	the first argument is neither a sheet nor a range.
`IllegalArgumentException`	the predicate is not a function, or the header position is not a positive integer.

Examples

In use

const sheet = SpreadsheetApp.getActiveSheet();

clearRowsByConditional(sheet, (values, position, row) => row.status === "done", {
  headerRow: 1
});

Within one block

const sheet = SpreadsheetApp.getActiveSheet();

// Only B2:D100 is read, and only those cells are cleared.
clearRowsByConditional(sheet.getRange("B2:D100"), (values) => values.every((cell) => cell === ""));

Source

src/appsscript/sheet/clearRowsByConditional.ts

23 September 2026

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

apps-script-utils 2.1.1 Help