deleteRowsByConditional

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

Every row is judged against the sheet as it was read, and the deletions then happen from the bottom upwards in consecutive blocks. That is what keeps a hand-written loop from deleting the wrong rows once the positions start shifting.

Rows are gone for good: clearRowsByConditional is the one that only empties them.

A sheet means its whole data range and whole rows are removed. A range means only the cells inside it: they are deleted and the ones below them move up, while the columns beside the range stay exactly where they are. Either way the predicate is given the position on the sheet, and the refusal to empty a sheet applies to the sheet form, where a sheet must keep a row.

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 removed.
`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();

deleteRowsByConditional(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 move up.
deleteRowsByConditional(sheet.getRange("B2:D100"), (values) => values.every((cell) => cell === ""));

Source

src/appsscript/sheet/deleteRowsByConditional.ts

23 September 2026

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

apps-script-utils 2.1.1 Help