Google Apps Script SpreadsheetApp

Clear and Set Conditional Formatting Rules to a Specific Range in Google Sheets with Apps Script

I’ve created a small (pseudo) class that more easily clears and creates conditional formatting rules in a Google Sheet tab with Google Apps Script.

Why?

Well in Google Apps Script, conditional formatting rules are all or nothing.

Alf Specifically GIFfrom Alf GIFs

You can only ever set, get or clear ALL rules in a specified Google Sheet tab.

So if you add a single rule to a sheet tab, all existing rules will be removed.

This means that each time you need to clear a rule or a portion of a rule or add in a new rule, you need to rebuild the entire rule set for that sheet tab.

It is an unpleasant experience.

The script below simplifies this process into some common clear and create processes for your conditional formatting.

Let me know in the comments below if you have a suggestion for another method for the class.

One last thing.

If you want to understand what is going on with the code (You are my kind of peeps), check out the video tutorial series.

https://www.youtube.com/watch?v=coko7zUXsHk

A Simple Apps Script Class to Clear & Set Conditional Formatting in Google Sheets (https://www.youtube.com/watch?v=coko7zUXsHk)

The Code: Range_ConditionalFormatting()

To add this script to your own projects, I recommend that you create a new Google Apps Script file (page) and paste the code in there.

Check out the chapters below on how to use the class.

/**
 * #### Clear and Set by range conditional formattting. ####
 * 
 * Clears and sets conditional formatting by range.
 * This is a sudo class. 
 * @author Scott Donald [scott@yagisanatode.com]
 * @see {https://yagisanatode.com/clear-and-set-conditional-formatting-rules-to-a-specific-range-in-google-sheets-with-apps-script/} for further informtation.
 */


/**
 * @typedef {Range_ConditionalFormattingMethods}
 * @param {SpreadsheetApp.Sheet} sheet - the target Sheet tab
 * @property {function} clearRule
 * @property {function} setRules
 * @returns Range_ConditionalFormattingMethods
 */
function Range_ConditionalFormatting(sheet) {

  /**
 * @typedef {Object} matrixRange
 * @property {Number} rs = row start
 * @property {Number} re = row end
 * @property {Number} cs = col start
 * @property {Number} ce = col end
 */

  /**
   * Checks sample ranges agains target ranges and removes 
   * any overlapping ranges. 
   * @param {matrixRange[]} targets - Selected ranges used to erase
   * @param {matirxRange[]} erased - Range to erase if it overlaps
   * @returns {matrixRange[]}
   */
  function checkRangeOverlapAndRebuild_(targets, erased) {

    console.log("checkRangeOverlapAndRebuild_")
    console.log(targets)
    console.log(erased)

    // On each iteration check the range
    let newRanges = []
    let checkRanges = [...erased]
    let checkRangesLen = checkRanges.length


    /**
     * Checks row overlaps and creates new ranges.
     * @param {matrixRange} s - sample range. 
     * @param {matrixRange} t - target range. 
     */
    function rowCheck(s, t) {
      if (s.rs < t.rs) {
        // If s row starts before t start.
        if (s.re <= t.re) {
          // If s row ends at or before t end. (add: top)
          let n1 = { rs: s.rs, re: t.rs - 1, cs: s.cs, ce: s.ce }
          newRanges.push(n1)

          s.rs = t.rs
          colCheck(s, t)

        } else if (s.re > t.re) {
          // If s row ends after t end. (add: top, bottom)
          let n1 = { rs: s.rs, re: t.rs - 1, cs: s.cs, ce: s.ce }
          let n4 = { rs: t.re + 1, re: s.re, cs: s.cs, ce: s.ce }
          newRanges.push(n1, n4)

          s.rs = t.rs
          s.re = t.re
          colCheck(s, t)
        }
      } else if (s.rs >= t.rs) {
        // If the s row range starts inside the t. 
        if (s.re > t.re) {
          // If the s row ends after the t end. (add:bottom)
          let n4 = { rs: t.re + 1, re: s.re, cs: s.cs, ce: s.ce }
          newRanges.push(n4)
          s.re = t.re
        }

        colCheck(s, t)
      }
    }

    /**
     * Checks columns overlaps and creates new ranges.
     * @param {matrixRange} s - sample range. 
     * @param {matrixRange} t - target range. 
     */
    function colCheck(s, t) {
      if (s.cs < t.cs) {
        // If s col start before t col start
        if (s.ce <= t.ce) {
          //If s col ends at or before t ends. (add: left)
          let n2 = { rs: s.rs, re: s.re, cs: s.cs, ce: t.cs - 1 }
          newRanges.push(n2)

        } else if (s.ce > t.ce) {
          // If s col ends after t end. (add: left, right)
          let n2 = { rs: s.rs, re: s.re, cs: s.cs, ce: t.cs - 1 }
          let n3 = { rs: s.rs, re: s.re, cs: t.ce + 1, ce: s.ce }
          newRanges.push(n2, n3)
        }
      } else if (s.cs >= t.cs && s.ce > t.ce) {
        let n3 = { rs: s.rs, re: s.re, cs: t.ce + 1, ce: s.ce }
        newRanges.push(n3)
      }
    }


    // Iterate over each target area to check range overlaps.
    targets.forEach(t => {

      // Loop through checkRanges
      // This allows us to check for any ranges we create when we have 
      // mulitple target ranges.
      while (checkRangesLen > 0) {
        const s = checkRanges[checkRangesLen - 1]


        // If s does not touch t, add range. (do first for quick exit)
        if (
          s.re < t.rs ||
          s.rs > t.re ||
          s.ce < t.cs ||
          s.cs > t.ce
        ) {
          newRanges.push(s) // Pushes existing ranges. 
        } else {
          rowCheck(s, t)
        }

        checkRanges.pop()
        checkRangesLen = checkRanges.length
      }

      checkRanges = [...newRanges] // Review the new check range on the next target
      newRanges = []

      checkRangesLen = checkRanges.length
    })

    return checkRanges
  }



  const publicAPI = {}

  /**
   * @typedef {boolean} clearRule
   * @param {SpreadsheetApp.Range | SpreadsheetApp.Range[]} rangeOrRanges - target range or ranges.
   * @param {Number} [clearType] - 0 = Clear exactly matching range.
   * - 1 = Clear only within range. 
   * - 2 = Clear withing and partial ranges. 
   * the targe range will be removed from the conditional formatting. 
   */
  publicAPI.clearRule = function (rangeOrRanges, clearType = 0) {


    /** @type {SpreadsheetApp.Range[]} */
    const ranges = rangeOrRanges.constructor == Array ? rangeOrRanges : [rangeOrRanges]
    const tgtRanges = clearType == 0
      ? ranges.map(r => r.getA1Notation()) // We need A1 if zero.
      : ranges.map(r => {
        return {
          rs: r.getRow(),
          re: r.getLastRow(),
          cs: r.getColumn(),
          ce: r.getLastColumn()
        }
      })

    const cur_rules = sheet.getConditionalFormatRules()

    let updated_rules = []
    let hasRangeChange = false




    // interate over the current conditional formatting
    updated_rules = cur_rules.reduce((acc, crule) => {
      // - Iterate over current ranges and delete any 
      const cruleRanges = crule.getRanges()

      // let remainingRuleA1ranges = []

      const remainingRuleA1ranges = cruleRanges.reduce((acc2, r) => {
        switch (clearType) {
          case 0: // CLEAR EXACT MATCH

            // - If a range matches, delete. 
            if (tgtRanges.includes(r.getA1Notation())) {
              hasRangeChange = true
              return acc2
            }

            break


          case 1: // CLEAR ALL RANGES WITHIN SPECIFIED RANGE

            // - If a range fits within any of the target ranges, delete. 
            const hasMatch = tgtRanges.some(tr => {
              if (
                r.getRow() >= tr.rs &&
                r.getLastRow() <= tr.re &&
                r.getColumn() >= tr.cs &&
                r.getLastColumn() <= tr.ce
              ) {
                return true
              }
              return false
            })

            if (hasMatch) {
              hasRangeChange = true
              return acc2
            }

            break


          case 2: // CLEAR ALL RANGE OVERLAPS WITHIN SPECIFIED RANGE
            const cruleRangeLoc = [{
              rs: r.getRow(),
              re: r.getLastRow(),
              cs: r.getColumn(),
              ce: r.getLastColumn(),
            }]

            const cruleNewRanges = checkRangeOverlapAndRebuild_(
              tgtRanges, cruleRangeLoc
            )

            // If there has been a change
            if (JSON.stringify(cruleNewRanges) != JSON.stringify(cruleRangeLoc)) {
              // Convert to A1 Notation
              cruleNewRangesA1 = cruleNewRanges.map(cruleRange => {

                return sheet.getRange(
                  cruleRange.rs,
                  cruleRange.cs,
                  cruleRange.re - cruleRange.rs + 1,
                  cruleRange.ce - cruleRange.cs + 1,
                )
              })

              hasRangeChange = true
              return acc2 = acc2.concat(cruleNewRangesA1)
            }

            break
        } // SWITCH ENDS

        // Nothing deleted.
        return acc2 = acc2.concat(r)
      }, [])


      const remainingRulesA1rangesLength = remainingRuleA1ranges.length

      // If there are no remaining ranges in the 
      if (remainingRulesA1rangesLength == 0) return acc

      // If there is a difference in # of ranges after check, rebuild cond fmt rule
      if (hasRangeChange) {
        console.log("range has been removed. ")
        let cruleCopy = crule.copy()
        cruleCopy.setRanges(remainingRuleA1ranges)
        cruleCopy.build()

        acc = acc.concat(cruleCopy)

        return acc
      }

      // If the range was not impacted  return the rule. 
      acc = acc.concat(crule)
      return acc


    }, [])


    // Update the conditional formatting rules. 
    sheet.setConditionalFormatRules(updated_rules)

  }




  /**
   * @typedef {SpreadsheetApp.ConditionalFormatRule} setRules
   * @param {SpreadsheetApp.ConditionalFormatRule[]} rules - array of conitional formatting rules.
   * @param {Number} [position] - End of rules by default (-1)
   * - 0 Start of rules. Positive numbers apply position up to max length of rule set. 
   * - -1 End or rules negative numbers position in reverse from last rule to start up to zero.
   */
  publicAPI.setRules = function (rules, position = -1) {
    let newRules = sheet.getConditionalFormatRules()
    const ruleLen = newRules.length

    let pos = -1

    if (position > -1) {
      if (position > ruleLen) {
        pos = ruleLen
      } else {
        pos = position
      }
    } else {

      const posNeg = ruleLen + position + 1
      console.log(position, posNeg)
      if (posNeg < 0) {
        pos = 0
      } else {
        pos = posNeg
      }
    }

    console.log("POS", pos,
      "\nCur rules length", sheet.getConditionalFormatRules().length,
      "\nNew rules length", ruleLen

    )

    // Get current rules

    newRules.splice(pos, 0, ...rules)

    sheet.setConditionalFormatRules(newRules)
  }

  return publicAPI
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

/**

* #### Clear and Set by range conditional formattting. ####

* Clears and sets conditional formatting by range.

* This is a sudo class.

* @author Scott Donald [scott@yagisanatode.com]

* @see {https://yagisanatode.com/clear-and-set-conditional-formatting-rules-to-a-specific-range-in-google-sheets-with-apps-script/} for further informtation.

/**

* @typedef {Range_ConditionalFormattingMethods}

* @param {SpreadsheetApp.Sheet} sheet - the target Sheet tab

* @property {function} clearRule

* @property {function} setRules

* @returns Range_ConditionalFormattingMethods

function Range_ConditionalFormatting(sheet) {

/**

* @typedef {Object} matrixRange

* @property {Number} rs = row start

* @property {Number} re = row end

* @property {Number} cs = col start

* @property {Number} ce = col end

/**

* Checks sample ranges agains target ranges and removes

* any overlapping ranges.

* @param {matrixRange[]} targets - Selected ranges used to erase

* @param {matirxRange[]} erased - Range to erase if it overlaps

* @returns {matrixRange[]}

function checkRangeOverlapAndRebuild_(targets, erased) {

console.log("checkRangeOverlapAndRebuild_")

console.log(targets)

console.log(erased)

// On each iteration check the range

let newRanges = []

let checkRanges = [...erased]

let checkRangesLen = checkRanges.length

/**

* Checks row overlaps and creates new ranges.

* @param {matrixRange} s - sample range.

* @param {matrixRange} t - target range.

function rowCheck(s, t) {

if (s.rs < t.rs) {

// If s row starts before t start.

if (s.re <= t.re) {

// If s row ends at or before t end. (add: top)

let n1 = { rs: s.rs, re: t.rs - 1, cs: s.cs, ce: s.ce }

newRanges.push(n1)

s.rs = t.rs

colCheck(s, t)

} else if (s.re > t.re) {

// If s row ends after t end. (add: top, bottom)

let n1 = { rs: s.rs, re: t.rs - 1, cs: s.cs, ce: s.ce }

let n4 = { rs: t.re + 1, re: s.re, cs: s.cs, ce: s.ce }

newRanges.push(n1, n4)

s.rs = t.rs

s.re = t.re

colCheck(s, t)

}

} else if (s.rs >= t.rs) {

// If the s row range starts inside the t.

if (s.re > t.re) {

// If the s row ends after the t end. (add:bottom)

let n4 = { rs: t.re + 1, re: s.re, cs: s.cs, ce: s.ce }

newRanges.push(n4)

s.re = t.re

}

colCheck(s, t)

}

/**

* Checks columns overlaps and creates new ranges.

* @param {matrixRange} s - sample range.

* @param {matrixRange} t - target range.

function colCheck(s, t) {

if (s.cs < t.cs) {

// If s col start before t col start

if (s.ce <= t.ce) {

//If s col ends at or before t ends. (add: left)

let n2 = { rs: s.rs, re: s.re, cs: s.cs, ce: t.cs - 1 }

newRanges.push(n2)

} else if (s.ce > t.ce) {

// If s col ends after t end. (add: left, right)

let n2 = { rs: s.rs, re: s.re, cs: s.cs, ce: t.cs - 1 }

let n3 = { rs: s.rs, re: s.re, cs: t.ce + 1, ce: s.ce }

newRanges.push(n2, n3)

}

} else if (s.cs >= t.cs && s.ce > t.ce) {

let n3 = { rs: s.rs, re: s.re, cs: t.ce + 1, ce: s.ce }

newRanges.push(n3)

}

// Iterate over each target area to check range overlaps.

targets.forEach(t => {

// Loop through checkRanges

// This allows us to check for any ranges we create when we have

// mulitple target ranges.

while (checkRangesLen > 0) {

const s = checkRanges[checkRangesLen - 1]

// If s does not touch t, add range. (do first for quick exit)

if (

s.re < t.rs ||

s.rs > t.re ||

s.ce < t.cs ||

s.cs > t.ce

) {

newRanges.push(s) // Pushes existing ranges.

} else {

rowCheck(s, t)

}

checkRanges.pop()

checkRangesLen = checkRanges.length

}

checkRanges = [...newRanges] // Review the new check range on the next target

newRanges = []

checkRangesLen = checkRanges.length

})

return checkRanges

}

const publicAPI = {}

/**

* @typedef {boolean} clearRule

* @param {SpreadsheetApp.Range | SpreadsheetApp.Range[]} rangeOrRanges - target range or ranges.

* @param {Number} [clearType] - 0 = Clear exactly matching range.

* - 1 = Clear only within range.

* - 2 = Clear withing and partial ranges.

* the targe range will be removed from the conditional formatting.

publicAPI.clearRule = function (rangeOrRanges, clearType = 0) {

/** @type {SpreadsheetApp.Range[]} */

const ranges = rangeOrRanges.constructor == Array ? rangeOrRanges : [rangeOrRanges]

const tgtRanges = clearType == 0

? ranges.map(r => r.getA1Notation()) // We need A1 if zero.

: ranges.map(r => {

return {

rs: r.getRow(),

re: r.getLastRow(),

cs: r.getColumn(),

ce: r.getLastColumn()

}

})

const cur_rules = sheet.getConditionalFormatRules()

let updated_rules = []

let hasRangeChange = false

// interate over the current conditional formatting

updated_rules = cur_rules.reduce((acc, crule) => {

// - Iterate over current ranges and delete any

const cruleRanges = crule.getRanges()

// let remainingRuleA1ranges = []

const remainingRuleA1ranges = cruleRanges.reduce((acc2, r) => {

switch (clearType) {

case 0: // CLEAR EXACT MATCH

// - If a range matches, delete.

if (tgtRanges.includes(r.getA1Notation())) {

hasRangeChange = true

return acc2

}

break

case 1: // CLEAR ALL RANGES WITHIN SPECIFIED RANGE

// - If a range fits within any of the target ranges, delete.

const hasMatch = tgtRanges.some(tr => {

if (

r.getRow() >= tr.rs &&

r.getLastRow() <= tr.re &&

r.getColumn() >= tr.cs &&

r.getLastColumn() <= tr.ce

) {

return true

}

return false

})

if (hasMatch) {

hasRangeChange = true

return acc2

}

break

case 2: // CLEAR ALL RANGE OVERLAPS WITHIN SPECIFIED RANGE

const cruleRangeLoc = [{

rs: r.getRow(),

re: r.getLastRow(),

cs: r.getColumn(),

ce: r.getLastColumn(),

}]

const cruleNewRanges = checkRangeOverlapAndRebuild_(

tgtRanges, cruleRangeLoc

)

// If there has been a change

if (JSON.stringify(cruleNewRanges) != JSON.stringify(cruleRangeLoc)) {

// Convert to A1 Notation

cruleNewRangesA1 = cruleNewRanges.map(cruleRange => {

return sheet.getRange(

cruleRange.rs,

cruleRange.cs,

cruleRange.re - cruleRange.rs + 1,

cruleRange.ce - cruleRange.cs + 1,

)

})

hasRangeChange = true

return acc2 = acc2.concat(cruleNewRangesA1)

}

break

} // SWITCH ENDS

// Nothing deleted.

return acc2 = acc2.concat(r)

}, [])

const remainingRulesA1rangesLength = remainingRuleA1ranges.length

// If there are no remaining ranges in the

if (remainingRulesA1rangesLength == 0) return acc

// If there is a difference in # of ranges after check, rebuild cond fmt rule

if (hasRangeChange) {

console.log("range has been removed. ")

let cruleCopy = crule.copy()

cruleCopy.setRanges(remainingRuleA1ranges)

cruleCopy.build()

acc = acc.concat(cruleCopy)

return acc

}

// If the range was not impacted return the rule.

acc = acc.concat(crule)

return acc

}, [])

// Update the conditional formatting rules.

sheet.setConditionalFormatRules(updated_rules)

}

/**

* @typedef {SpreadsheetApp.ConditionalFormatRule} setRules

* @param {SpreadsheetApp.ConditionalFormatRule[]} rules - array of conitional formatting rules.

* @param {Number} [position] - End of rules by default (-1)

* - 0 Start of rules. Positive numbers apply position up to max length of rule set.

* - -1 End or rules negative numbers position in reverse from last rule to start up to zero.

publicAPI.setRules = function (rules, position = -1) {

let newRules = sheet.getConditionalFormatRules()

const ruleLen = newRules.length

let pos = -1

if (position > -1) {

if (position > ruleLen) {

pos = ruleLen

} else {

pos = position

}

} else {

const posNeg = ruleLen + position + 1

console.log(position, posNeg)

if (posNeg < 0) {

pos = 0

} else {

pos = posNeg

}

console.log("POS", pos,

"\nCur rules length", sheet.getConditionalFormatRules().length,

"\nNew rules length", ruleLen

)

// Get current rules

newRules.splice(pos, 0, ...rules)

sheet.setConditionalFormatRules(newRules)

}

return publicAPI

}

Note! Square brackets around parameters indicate optional parameters.

Class

The pseudo-class Range_ConditionalFormatting(sheet) tales one argument:

sheet: This is a Spreadsheet App Sheet class. Notated as SpreadsheetApp.Sheet in JS Doc.

function test_Range_ConditionalFormatting() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  Range_ConditionalFormatting(sheet). // .clearRule() or setRule()
}

function test_Range_ConditionalFormatting() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

Range_ConditionalFormatting(sheet). // .clearRule() or setRule()

}

Video link: Range_ConditionalFormatting(sheet)

Methods

Method	Return Type
clearRule()	Clears a rule or rules by a single range or array or ranges, based on 3 clearing approaches.
setRule()	Sets a rule or rules while maintaining the existing rules in the Sheet tab.

clearRule(rangeOrRanges, [clearType])

Clears the conditional formatting rules in a Google Sheet tab by the selected range or ranges and clear type while maintaining the existing conditional formatting rules in the Google Sheet tab.

Video link: clearRule method

Parameters

Name	Optional	Type	Description
rangeOrRanges		Range or Range Array	A SpreadsheetApp.Range or array of ranges that will be the target locations to clear.
clearType	✓	Number	The way the method should clear the range (see below) Default is clearType = 0

Name

Optional

Type

Description

rangeOrRanges

Range or Range Array

A SpreadsheetApp.Range or array of ranges that will be the target locations to clear.

clearType

✓

Number

The way the method should clear the range (see below)

Default is clearType = 0

Clear types

0 – Clears any conditional formatting rule that exactly matches the range.
1 – Clears any conditional formatting rule that has a range within the target range.
2 – Clears any conditional formatting rule or portions of the range of a rule that overlap the target range.

Examples

clearRule(range) – Single range and no optional clear type

Clears a conditional formatting range that exactly matches the single range provided.

function test_Range_ConditionalFormatting_range() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a range of formatting rules. 
  const range = sheet.getRange("B4:B7")
  console.log("Single Range Clear - exact match.")

  Range_ConditionalFormatting(sheet).clearRule(range)

}

function test_Range_ConditionalFormatting_range() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a range of formatting rules.

const range = sheet.getRange("B4:B7")

console.log("Single Range Clear - exact match.")

Range_ConditionalFormatting(sheet).clearRule(range)

}

Video link: clearRule(ranges) – Ranges and no optional clear type

clearRule(ranges) – Multiple ranges and no optional clear type

Clears the conditional formatting that exactly matches multiple ranges.

function test_Range_ConditionalFormatting_ranges() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a list of ranges
  const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

  console.log(ranges.length)

  Range_ConditionalFormatting(sheet).clearRule(ranges)

}

function test_Range_ConditionalFormatting_ranges() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a list of ranges

const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

console.log(ranges.length)

Range_ConditionalFormatting(sheet).clearRule(ranges)

}

clearRule(range, clearType = 0) – Single range with clear type zero- Exact match

Clears a conditional formatting range that exactly matches the array of ranges provided. Clear type zero (0) is the default clear type.

function test_Range_ConditionalFormatting_range_clear_exact() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a range of formatting rules. 
  const range = sheet.getRange("B4:B7")
  console.log("Single Range Clear - exact match.")

  Range_ConditionalFormatting(sheet).clearRule(range, 0)

}

function test_Range_ConditionalFormatting_range_clear_exact() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a range of formatting rules.

const range = sheet.getRange("B4:B7")

console.log("Single Range Clear - exact match.")

Range_ConditionalFormatting(sheet).clearRule(range, 0)

}

Video link: clearRule(ranges, 0) – Exact match

clearRule(ranges, clearType = 0) – Multiple ranges with clear type zero – Exact match

Clears the conditional formatting that exactly matches multiple ranges.

function test_Range_ConditionalFormatting_ranges_clear_exact() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a list of ranges
  const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

  console.log(ranges.length)

  Range_ConditionalFormatting(sheet).clearRule(ranges, 0)

}

function test_Range_ConditionalFormatting_ranges_clear_exact() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a list of ranges

const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

console.log(ranges.length)

Range_ConditionalFormatting(sheet).clearRule(ranges, 0)

}

clearRule(range, clearType = 1) – Single range with clear type one – Within range

Clears a conditional formatting rule range that has a range equal to or within the target range.

function test_Range_ConditionalFormatting_range_clear_within() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a range of formatting rules. 
  const range = sheet.getRange("B4:B7")
  console.log("Single Range Clear - exact match.")

  Range_ConditionalFormatting(sheet).clearRule(range, 1)

}

function test_Range_ConditionalFormatting_range_clear_within() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a range of formatting rules.

const range = sheet.getRange("B4:B7")

console.log("Single Range Clear - exact match.")

Range_ConditionalFormatting(sheet).clearRule(range, 1)

}

Video link: clearRule(ranges, 1) – Within range

clearRule(ranges, clearType = 1) – Multiple ranges with clear type zero- Within range

Clears all conditional formatting rule ranges equal to or within the target array of ranges.

function test_Range_ConditionalFormatting_ranges_clear_wihin() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a list of ranges
  const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

  console.log(ranges.length)

  Range_ConditionalFormatting(sheet).clearRule(ranges, 1)

}

function test_Range_ConditionalFormatting_ranges_clear_wihin() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a list of ranges

const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

console.log(ranges.length)

Range_ConditionalFormatting(sheet).clearRule(ranges, 1)

}

clearRule(range, clearType = 2) – Single range with clear type one – Overlaps

Clears a conditional formatting rule range that has a range equal to or within the target range or rebuilds the range where any range overlaps the target range removing that portion of the range.

function test_Range_ConditionalFormatting_range_clear_exact() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("TEST1")

  // Clear a range of formatting rules. 
  const range = sheet.getRange("B4:B7")
  console.log("Single Range Clear - exact match.")

  Range_ConditionalFormatting(sheet).clearRule(range, 2)

}

function test_Range_ConditionalFormatting_range_clear_exact() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("TEST1")

// Clear a range of formatting rules.

const range = sheet.getRange("B4:B7")

console.log("Single Range Clear - exact match.")

Range_ConditionalFormatting(sheet).clearRule(range, 2)

}

Video link: clearRule(ranges, 2) – Overlapping ranges

clearRule(ranges, clearType = 2) – Multiple ranges with clear type zero- Overlaps

Clears all conditional formatting rule ranges equal to or within the target array of ranges or rebuilds the range where any range overlaps the target range removing that portion of the range.

function test_Range_ConditionalFormatting_ranges_clear_exact() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("Sheet1")

  // Clear a list of ranges
  const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

  console.log(ranges.length)

  Range_ConditionalFormatting(sheet).clearRule(ranges, 2)

}

function test_Range_ConditionalFormatting_ranges_clear_exact() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("Sheet1")

// Clear a list of ranges

const ranges = ["B12:B15", "B20:B23", "B28:B31"].map(r => sheet.getRange(r))

console.log(ranges.length)

Range_ConditionalFormatting(sheet).clearRule(ranges, 2)

}

setRule(rules, [position])

The setRule method adds a conditional formatting rule or rules to an existing Google Sheet tab. It does not remove any existing rules in the selected tab.

The method has an optional position parameter that allows the user to customise where they wish to order the rule in relation to the existing rules on the Sheet tab.

Video link: setRule method

Parameters

Name	Optional	Type	Description
rules		Conditional Formatting Rules	A SpreadsheetApp.ConditionalFormatRule[] array of objects. This is an array of rules built with the Apps Script conditional formatting rule builder.
position	✓	Number	The position of the new rule in the existing set of rules. Default is position = -1, or the bottom of the rules array. A position of zero (0) sets the rule to the top of the array set. Positive numbers apply position up to max length of the rule set. -1 for end of the rule Rules with negative numbers are position from the last rule in reverse order up to zero.

Name

Optional

Type

Description

rules

Conditional Formatting Rules

SpreadsheetApp.ConditionalFormatRule[]

array of objects. This is an array of rules built with the Apps Script conditional formatting rule builder.

position

✓

Number

The position of the new rule in the existing set of rules.

Default is position = -1, or the bottom of the rules array.

A position of zero (0) sets the rule to the top of the array set.

Positive numbers apply position up to max length of the rule set.

-1 for end of the rule

Rules with negative numbers are position from the last rule in reverse order up to zero.

Examples

function test_Range_ConditionalFormatting_set() {
  const ss = SpreadsheetApp.getActiveSpreadsheet()
  const sheet = ss.getSheetByName("TEST4")
  let range

  const rule1 = SpreadsheetApp.newConditionalFormatRule()
    .whenTextEqualTo("1")
    .setBackground("#f9cb9c")

  const rule2 = SpreadsheetApp.newConditionalFormatRule()
    .whenTextEqualTo("2")
    .setBackground("#b4a7d6")

  // TEST 1 - ADD RULES - NO POSITION
  range = sheet.getRange("A3:L8")
  rule1
    .setRanges([range])
    .build()

  rule2
    .setRanges([range])
    .build()

  Range_ConditionalFormatting(sheet).setRules([rule1, rule2])


  // TEST 2 - ADD RULES - BOTTOM OF RULES ARRAY
  range = sheet.getRange("A14:L18")
  rule1
    .setRanges([range])
    .build()

  rule2
    .setRanges([range])
    .build()

  Range_ConditionalFormatting(sheet).setRules([rule1, rule2], -1)


  // TEST 3 - ADD RULES - TOP OF RULES ARRAY
  range = sheet.getRange("A24:L28")
  rule1
    .setRanges([range])
    .build()

  rule2
    .setRanges([range])
    .build()

  Range_ConditionalFormatting(sheet).setRules([rule1, rule2], 0)


  // TEST 4 - ADD RULES - AFTER 1ST RULE
  range = sheet.getRange("A34:L38")
  rule1
    .setRanges([range])
    .build()

  rule2
    .setRanges([range])
    .build()

  Range_ConditionalFormatting(sheet).setRules([rule1, rule2], -6)

}

function test_Range_ConditionalFormatting_set() {

const ss = SpreadsheetApp.getActiveSpreadsheet()

const sheet = ss.getSheetByName("TEST4")

let range

const rule1 = SpreadsheetApp.newConditionalFormatRule()

.whenTextEqualTo("1")

.setBackground("#f9cb9c")

const rule2 = SpreadsheetApp.newConditionalFormatRule()

.whenTextEqualTo("2")

.setBackground("#b4a7d6")

// TEST 1 - ADD RULES - NO POSITION

range = sheet.getRange("A3:L8")

rule1

.setRanges([range])

.build()

rule2

.setRanges([range])

.build()

Range_ConditionalFormatting(sheet).setRules([rule1, rule2])

// TEST 2 - ADD RULES - BOTTOM OF RULES ARRAY

range = sheet.getRange("A14:L18")

rule1

.setRanges([range])

.build()

rule2

.setRanges([range])

.build()

Range_ConditionalFormatting(sheet).setRules([rule1, rule2], -1)

// TEST 3 - ADD RULES - TOP OF RULES ARRAY

range = sheet.getRange("A24:L28")

rule1

.setRanges([range])

.build()

rule2

.setRanges([range])

.build()

Range_ConditionalFormatting(sheet).setRules([rule1, rule2], 0)

// TEST 4 - ADD RULES - AFTER 1ST RULE

range = sheet.getRange("A34:L38")

rule1

.setRanges([range])

.build()

rule2

.setRanges([range])

.build()

Range_ConditionalFormatting(sheet).setRules([rule1, rule2], -6)

}

Video Tutorial Series

You can check out the playlist for Conditional formatting here.

Apps Script – Google Sheets Conditional Formatting Playlist

The video tutorials:

Clear Conditional Formatting Rules by Exact Match in Google Sheets with Apps Script

Clear Conditional Formatting Rules Within a Range in Google Sheets with Apps Script

Clear Conditional Formatting Rules that Overlap a Target Range in Google Sheets with Apps Script

Add Conditional Formatting Rules to a Google Sheet Tab with Apps Script

Conclusion

Being such a short pseudo-class it is hardly worth slowing down your script by making this into a library. I recommend you just add it to your existing project for simplicity and performance.

If you think there are any other methods worth adding, please let me know in the comments.

I would also love to hear how you used this in your own projects.

Need help with Google Workspace development?

Go something to solve bigger than Chat GPT?

I can help you with all of your Google Workspace development needs, from custom app development to integrations and security. I have a proven track record of success in helping businesses of all sizes get the most out of Google Workspace.

Schedule a free consultation today to discuss your needs and get started or learn more about our services here.

~Yagi.

Prevent consecutive clicks of Google Sheets Image Buttons in with Lock Service and Google Apps Script

Ever seen an overzealous user madly clicking on an image button in Google Sheets to run an automation script? It’s maddening, frustrating and most importantly, may cause errors in your beautifully crafted code.

How Iplaysmash GIFfrom How Iplaysmash GIFs

In this short tutorial, we explore how to use Google Apps Script’s Lock Service to prevent users from executing your code from your image button while the original instance of the code is still running.

Grab a copy of the starter sheet below to play along.

To the Starter Sheet

Continue reading “Prevent consecutive clicks of Google Sheets Image Buttons in with Lock Service and Google Apps Script”

Add the Editor’s Email when they Tick the Check Box in Google Sheets with Apps Script

This tutorial is for Google Workspace Domain accounts.

Recently, I was a guest interviewee at a Google Workspace Developer Summit in Singapore and an attendee asked me how they could automatically add the editor’s email to an adjacent cell when the user checks a check box in Google Sheets.

This can be incredibly handy for project managers to see when a user completes a task or, at a glance, who edited a row.

Of course, there are some simple ways of doing this out-of-the-box within Google Sheets.

A simple right-click > Show edit history on any cell can reveal who has edited the cell in the past.
If you want a more detailed history of edits on your Google Sheet workbook then you can always select the version history button in the top right of your Sheet.
The ‘clock’ icon here opens the version history page.

The problem with these options is that it is not there on the screen for the user to quickly see who edited what line.

In this tutorial, we are going to use some Google Apps Script magic to automatically add the editor’s email to the row when they click that checkbox.

Let’s dive in!

Continue reading “Add the Editor’s Email when they Tick the Check Box in Google Sheets with Apps Script”

How to Sort Tabs in Google Sheets with Google Apps Script

Sometimes your Google Sheet tabs can get out of hand. They can be mixed up and confusing to users. It’s often necessary to simply sort them in ascending or descending order.

In this tutorial, we will use Google Apps Script to sort tabs in Google Sheets. We’ll also use a handy menu bar to quickly run the sort.

The approach below relies on a natural sort. In a normal sort where you also have numbers say:

"2. Cheese", "10. Pizza", "1. Bananas"

Then you ran your sort, you would not get what your expected but rather:

"1. Bananas", "10. Pizza", "2. Cheese"

With a natural sort, we consider the number numerically, rather than as characters. This means our sort would come out as expected:

"1. Bananas", "2. Cheese", "10. Pizza"

You can learn more about creating the Apps Script by following the video below or you can jump down and grab a copy of your code and run it in your own project.

You can grab the starter Google Sheet Here:

Sorting Google Sheet Tabs – Starter Sheet

Sort Tabs in Google Sheets – Video

https://youtu.be/a7l6OEkMkIg

How to Sort Tabs in Google Sheets with Google Apps Script (https://youtu.be/a7l6OEkMkIg)

The Code

Step 1: In your Google Sheet, Go to Extensions > Apps Script.

Step 2: copy the code from below and paste it into the edits and save.

Step 3: Next, reload the Google Sheet. You will see a menu item called Extras. Click it and you will see your two sort options.

Step 4: Go ahead and click an option.

You should see your tabs being sorted.

Step 5: You will be prompted to run authorisation of the script the first time the script is run. You can learn more about this here:

Running Google Apps Script for the first time.

Step 6: Select an option again and you will see the tabs being sorted.

If you have found the tutorial helpful, why not shout me a coffee ☕? I'd really appreciate it.

/**
 * Creates a menu item for ascending and descending sheet tab sort.
 */
function onOpen(){
  const ui = SpreadsheetApp.getUi()
  
  ui
    .createMenu("Extras")
    .addItem("Sort tabs Asc","tabSorter.ascending")
    .addItem("Sort tabs Desc","tabSorter.descending")
    .addToUi()

}



/**
 * Object container to direct tab sorts for either ascending or descening order.
 */
const tabSorter = {
  ascending: function(){this.sortTabs(true)},
  descending: function(){this.sortTabs(false)},


  /**
   * Naturally sort tabs. This means where there are number, 
   * the sort will order them in numerical order. e,g, 1, 2, 10, "Car", "Goat"
   * @param {boolean} isAscending - if true will sort ascending, otherwise descending.
   */
  sortTabs: function(isAscending){
  const ss = SpreadsheetApp.getActiveSpreadsheet();

  const sheets = ss.getSheets(); 

  // Enable language sensitive string comparison.
  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
  const collator = new Intl.Collator(undefined, {
    numeric: true, // Sets numeric collation so 1 < 2 < 10
    sensitivity: 'base' // Ignores accents and other diacritic marks in lettering.
  });

  // Sorts the sheet.
  let sheetNames = sheets.sort((a,b) => {
    // Compares first sorted sheet name value against last sorted sheet name value.
    return collator.compare(a.getName(), b.getName())
  })

  // If set to descending the sheetNames lists is ignored.
  sheetNames = (!isAscending)? sheetNames.reverse(): sheetNames;

  // Iterates through each sheet sets it to activve and updates it order.
  sheetNames.forEach((sheet, idx) => {

    ss.setActiveSheet(sheet)
    ss.moveActiveSheet(idx + 1) // Sheet tab indexes start from one so we must add one.

  });
  }
};

/**

* Creates a menu item for ascending and descending sheet tab sort.

function onOpen(){

const ui = SpreadsheetApp.getUi()

.createMenu("Extras")

.addItem("Sort tabs Asc","tabSorter.ascending")

.addItem("Sort tabs Desc","tabSorter.descending")

.addToUi()

}

/**

* Object container to direct tab sorts for either ascending or descening order.

const tabSorter = {

ascending: function(){this.sortTabs(true)},

descending: function(){this.sortTabs(false)},

/**

* Naturally sort tabs. This means where there are number,

* the sort will order them in numerical order. e,g, 1, 2, 10, "Car", "Goat"

* @param {boolean} isAscending - if true will sort ascending, otherwise descending.

sortTabs: function(isAscending){

const ss = SpreadsheetApp.getActiveSpreadsheet();

const sheets = ss.getSheets();

// Enable language sensitive string comparison.

// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator

const collator = new Intl.Collator(undefined, {

numeric: true, // Sets numeric collation so 1 < 2 < 10

sensitivity: 'base' // Ignores accents and other diacritic marks in lettering.

});

// Sorts the sheet.

let sheetNames = sheets.sort((a,b) => {

// Compares first sorted sheet name value against last sorted sheet name value.

return collator.compare(a.getName(), b.getName())

})

// If set to descending the sheetNames lists is ignored.

sheetNames = (!isAscending)? sheetNames.reverse(): sheetNames;

// Iterates through each sheet sets it to activve and updates it order.

sheetNames.forEach((sheet, idx) => {

ss.setActiveSheet(sheet)

ss.moveActiveSheet(idx + 1) // Sheet tab indexes start from one so we must add one.

});

}

};

Need help with Google Workspace development?

Go something to solve bigger than Chat GPT?

Schedule a free consultation today to discuss your needs and get started or learn more about our services here.

Code Breakdown

onOpen()

/**
 * Creates a menu item for ascending and descending sheet tab sort.
 */
function onOpen(){
  const ui = SpreadsheetApp.getUi()
  
  ui
    .createMenu("Extras")
    .addItem("Sort tabs Asc","tabSorter.ascending")
    .addItem("Sort tabs Desc","tabSorter.descending")
    .addToUi()

}

/**

* Creates a menu item for ascending and descending sheet tab sort.

function onOpen(){

const ui = SpreadsheetApp.getUi()

.createMenu("Extras")

.addItem("Sort tabs Asc","tabSorter.ascending")

.addItem("Sort tabs Desc","tabSorter.descending")

.addToUi()

}

The onOpen() function is a Google Apps Script simple trigger that runs automatically when the user opens the Google Sheet.

Line 5: In our example, we call the Spreadsheet App UI class, so that we can build the menu.

Line 8: To create a menu we use the Create Menu method and add the menu label “Extras” as an argument.

Lines 9-10: Next, we can add menus to the main menu header with the Add Item method. These menus take a menu label and then a function or an object method that will run when the menu is selected. Ensure that you don’t include parentheses in these arguments and contain them in a string.

Line 11: Finally, we need to build the menu by adding all the menu items to the UI.

You can learn more about building menus in Google Sheets, Docs and Slides here:

How to build a menu item in Google Sheets

The Sheet Tab Sorter object

The tabSorter object contains 3 properties:

ascending
descending
sortTab

const tabSorter = {
  ascending: <em>method</em>,
  descending: <em>method</em>,
  
  ... 
  sortTabs: <em>method</em>

  ...

const tabSorter = {

ascending: method,

descending: method,

...

sortTabs: method

...

Ascending and Descending Property Methods

Both of these property methods run the sortTabs method providing either true for ascending or false for descending as the argument.

We need to encapsulate these method calls inside their own anonymous functions so that they don’t run automatically when the menu is loaded.

ascending: function(){this.sortTabs(true)},
descending: function(){this.sortTabs(false)},

The sort Google Sheet Tabs machine (sortTabs)

The sortTabs property does all the heavy lifting in this object.

It takes a boolean as an argument that will determine if the sort is ascending or descending.

Get a list of sheets

  const ss = SpreadsheetApp.getActiveSpreadsheet();

  const sheets = ss.getSheets(); ss.sheet

const ss = SpreadsheetApp.getActiveSpreadsheet();

const sheets = ss.getSheets(); ss.sheet

Our first task is to get an array containing all the Google Sheets in the currently active sheet. We can do this with the SpreadSheet App Get Sheets method. This will contain an array with all the methods available for each found sheet tab.

Using Intl Collator for natural sorting

We want to sort our sheet tabs naturally just in case we have numbers in the name of the tab (e.g. “1”, “2”, “4. Cake”). We can do this with the JavaScript Intl.Collator object to sort the sheet tabs in a natural order, meaning that numeric values are sorted in numerical order and text values are sorted alphabetically. You can modify this function to use a different sorting algorithm or change the sorting order.

  const collator = new Intl.Collator(undefined, {
    numeric: true, // Sets numeric collation so 1 < 2 < 10
    sensitivity: 'base' // Ignores accents and other diacritic marks in lettering.
  });

const collator = new Intl.Collator(undefined, {

numeric: true, // Sets numeric collation so 1 < 2 < 10

sensitivity: 'base' // Ignores accents and other diacritic marks in lettering.

});

Line 2: Here, we create a new Intl.Collator constructor. The first optional parameter of the constructor defines the locale or language tab. We don’t need this option, so we set it to ‘undefined’.

The second parameter sets the options for the collator.

Line 3: First, we use the numeric property and set it to true. This will allow us to order the numbers properly so that 1 < 2 <10.

Line 4: Secondly, we set the sensitivity to base. This means that we do not take into account any accents or other markings on letter characters. If you are using this Google Sheets sort tab code in other languages, then you might want to modify this.

Sort Google Sheet tabs Apps Script-side

Now that we have our collator set up we use the JavaScript sort method to sort through the array of sheet names.

  // Sorts the sheet.
  let sheetNames = sheets.sort((a,b) => {
    // Compares first sorted sheet name value against last sorted sheet name value.
    return collator.compare(a.getName(), b.getName())
  })

// Sorts the sheet.

let sheetNames = sheets.sort((a,b) => {

// Compares first sorted sheet name value against last sorted sheet name value.

return collator.compare(a.getName(), b.getName())

})

Line 2: Here, we use an arrow function with a standard a, b parameter set. These parameters refer to the first and second elements of comparison respectively.

Line 3: Use our collator and apply the compare method to compare the sheet names against each other.

Reversing the sort

  // If set to descending the sheetNames lists is ignored.
  sheetNames = (!isAscending)? sheetNames.reverse(): sheetNames;

1 2	// If set to descending the sheetNames lists is ignored. sheetNames = (!isAscending)? sheetNames.reverse(): sheetNames;

If isAscending parameter of the sortTabs method is set to false, then we use JavaScript reverse() to reverse the array order of the sheetNames.

Updating the Google Sheet tabs to the desired order

Finally, once our array is in the desired order we need to update the Google Sheet with the new tab order.

  // Iterates through each sheet sets it to activve and updates it order.
  sheetNames.forEach((sheet, idx) => {

    ss.setActiveSheet(sheet)
    ss.moveActiveSheet(idx + 1) // Sheet tab indexes start from one so we must add one.

  });

// Iterates through each sheet sets it to activve and updates it order.

sheetNames.forEach((sheet, idx) => {

ss.setActiveSheet(sheet)

ss.moveActiveSheet(idx + 1) // Sheet tab indexes start from one so we must add one.

});

Line 2: First, we loop through the sheet names array with the JavaScript forEach() method.

Line 3: Inside each loop, we need to set the active sheet to the currently iterated sheet.

Line 4: Finally, we move the active sheet to the next position in the sheet tabs. Note that sheet indexes start from one (1) however our array index starts from zero (0). This is why we need to add one to the index.

Starting the sort after a set number of tabs

Perhaps you have an instruction tab or dashboards that you want to leave to the left of your sort. Here you can update the moveActiveSheet() by increasing the value to add to the index by the desired number plus 1.

Let’s say I have an ‘Instructions’ tab and a ‘Dashboard Tab’ that I want to keep to the far left and is not included in my sort list. my moveActievSheet() function would look like this:

ss.moveActiveSheet(idx + 3)

1	ss.moveActiveSheet(idx + 3)

Here I add 1 to the zero-based index and another 2 for the two tabs I want to keep in position.

Google Sheet Tabs by Date

Check out my bonus video on sorting tabs by leading date.

The Starter Sheet

https://youtu.be/Uvd6JjKqVCM

Sort Sheet Tabs by Date in Google Sheets with Apps Script (https://youtu.be/Uvd6JjKqVCM)

That’s all there is to it.

If you want to learn more about how to modify Google sheets tabs with Apps Script, check out these tutorials:

If you have found the tutorial helpful, why not shout me a coffee ☕? I'd really appreciate it.

Changelog

2024-05-31

Added table of contents.
Added video on sorting Google Sheet Tabs by leading date.
Added chapter on keeping static sheet tabs to the right and sorting after them. Thanks to Cassidy for the question.

Performance of Google Apps Script Text Finder Class on 2 Approaches to Searching Large Datasets

Inspired by research into a recent blog post, the Google Apps Script Text Finder Class’ Find All (findAll()) and Find Next (findNext()) methods were benchmarked over two different datasets containing 50,000 rows. The first dataset contained 1,000 cells matching the search text. The second dataset contained 100 matching cells.

For each dataset, a test was conducted to retrieve either the first 10 matching cells or the first 100 matching cells. The Find All and Find Next approaches were tested and compared on each test.

It was expected that Find Next would perform best on the condition where the dataset contained a large number of found items and only a small number of first cells needed to be reported. The benchmark results suggest that this hypothesis is most likely.

	First number of cells to retrieve	Test	Function	Avg. run time over 100 runs.	Fastest Function	Fastest Avg. Time	Avg. time Difference
1000 items to find	10	1	v2 findAll	1626.24	v3 findNext	1368.45	257.79
	10	1	v3 findNext	1368.45
	50	2	v2 findAll	1578.19	v2 findAll	1578.19	4993.61
	50	2	v3 findNext	6571.8
100 items to find	10	3	v2 findAll	360.94	v2 findAll	360.94	975.16
	10	3	v3 findNext	1336.1
	50	4	v2 findAll	377.13	v2 findAll	377.13	6175.59
	50	4	v3 findNext	6552.72

Table: The average time in milliseconds of 100 runs of each test of Apps Script Text Finder findAll() and findNext() methods. Image link for mobile-friendly viewers.

Method

Sample Data

Two columns of data 50,000 rows deep were generated for this test. Each cell in each column consisted of a number; either 1, 2, 3, 4 or 5. An equal spread of numbers 1 through 4 where added to each row. Each column differs by the number of 5s in each row:

Col A: 1,000 5’s
Col B: 100 5’s

Each column was then selected and randomised with: Data > Randomise range.

Test

Two functions are compared to test their performance based on four test conditions based on 100 runs of each test:

Retrieve the first 10 cells containing the search text where the range contains 1,000 matching search items.
Retrieve the first 50 cells containing the search text where the range contains 1,000 matching search items.
Retrieve the first 10 cells containing the search text where the range contains 100 matching search items.
Retrieve the first 50 cells containing the search text where the range contains 100 matching search items.

The time in milliseconds was recorded using the JavaScript Date.now() method before and after the functions were run. The difference in time in milliseconds was then appended to an array and added to a Google Sheet column for each test type. This culminated in 8 sets of 100 results.

The average of each test was then recorded and used to compare performance.

Note: Performance.now() is not available in Google Apps Script.

Code

All code and results can be found copied from this sheet:

Analysis of Google Apps Script Create Finder Class Retrieve n found values

To explore the code and run your own independent tests, make a copy of the Google Sheet: File > Make a copy.

More detailed breakdowns of the code for each test function can be found in the source tutorial.

Note! There is no v1. The version numbers refer to the tutorial related to this post.

Main Test RUN

This function ran all the test conditions. Modify colPastePosition to add the culminated times to the desired columns. Then uncomment the desired run.

function testRun(){
  const sheetName = "Test Data"
  const text = 5;
  const n_small = 10;
  const n_big = 50;
  const rangeLoc_1000items = "A2:A";
  const rangeLoc_100items = "B2:B";

  let start, end

  const colPastePosition = 10;


  const times = [];

  for(let i = 0; i < 100; i++){

    start = Date.now();

    // Test 1: 1000 items to find. Return first ten, V2.
    const results = test_v2(sheetName, text, n_small, rangeLoc_1000items);

    // // Test 2: 1000 items to find. Return first ten, V3.
    // const results = test_v3(sheetName, text, n_small, rangeLoc_1000items);

    // // Test 3: 1000 items to find. Return first 50, V2.
    // const results = test_v2(sheetName, text, n_big, rangeLoc_1000items);

    // // Test 4: 100 items to find. Return first 50, V3.
    // const results = test_v3(sheetName, text, n_big, rangeLoc_1000items);

    // // Test 5: 100 items to find. Return first ten, V2.
    // const results = test_v2(sheetName, text, n_small, rangeLoc_100items);

    // // Test 6: 100 items to find. Return first ten, V3.
    // const results = test_v3(sheetName, text, n_small, rangeLoc_100items);

    // // Test 7: 100 items to find. Return first 50, V2.
    // const results = test_v2(sheetName, text, n_big, rangeLoc_100items);

    // // Test 8: 100 items to find. Return first 50, V3.
    // const results = test_v3(sheetName, text, n_big, rangeLoc_100items);

    end = Date.now();

    times.push([end - start])



  }

  SpreadsheetApp.getActiveSpreadsheet()
    .getSheetByName("Test")
    .getRange(6,colPastePosition,100,1)
    .setValues(times)
  

}

function testRun(){

const sheetName = "Test Data"

const text = 5;

const n_small = 10;

const n_big = 50;

const rangeLoc_1000items = "A2:A";

const rangeLoc_100items = "B2:B";

let start, end

const colPastePosition = 10;

const times = [];

for(let i = 0; i < 100; i++){

start = Date.now();

// Test 1: 1000 items to find. Return first ten, V2.

const results = test_v2(sheetName, text, n_small, rangeLoc_1000items);

// // Test 2: 1000 items to find. Return first ten, V3.

// const results = test_v3(sheetName, text, n_small, rangeLoc_1000items);

// // Test 3: 1000 items to find. Return first 50, V2.

// const results = test_v2(sheetName, text, n_big, rangeLoc_1000items);

// // Test 4: 100 items to find. Return first 50, V3.

// const results = test_v3(sheetName, text, n_big, rangeLoc_1000items);

// // Test 5: 100 items to find. Return first ten, V2.

// const results = test_v2(sheetName, text, n_small, rangeLoc_100items);

// // Test 6: 100 items to find. Return first ten, V3.

// const results = test_v3(sheetName, text, n_small, rangeLoc_100items);

// // Test 7: 100 items to find. Return first 50, V2.

// const results = test_v2(sheetName, text, n_big, rangeLoc_100items);

// // Test 8: 100 items to find. Return first 50, V3.

// const results = test_v3(sheetName, text, n_big, rangeLoc_100items);

end = Date.now();

times.push([end - start])

}

SpreadsheetApp.getActiveSpreadsheet()

.getSheetByName("Test")

.getRange(6,colPastePosition,100,1)

.setValues(times)

}

test_v2 – Google Apps Script Text Finder Class- findAll()

Code breakdown can be found here: link.

This function retrieves the full list of all found cells using the findAll() method from the Text Finder Class. All available found items in the range are then stored in the found variable.

It then relies on a for-loop to iterate through each cell and collect the cell location using the Spreadsheet App Class’ range getA1Notation method. Each cell location is then stored in the locations variable as an array item before returning the array to the initialising function.

The for-loop breaks when the total number of required cell items (the position) equal the index variable (i) in the loop.

/**
 * Finds the first set of matching cells of n in length or less.
 * @param {string} sheetName - the name of the sheet tab. 
 * @param {string|number} text - text to search. 
 * @param {number} n - the max number of items to report.
 * @param {string} rangeLoc - A1- Notation of selected range.
 * @return {array} - Array of cell positions of the found match.
 */
function test_v2(sheetName, text, n, rangeLoc){
  const position = n - 1;

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(sheetName);
  const range = sheet.getRange(rangeLoc)

  const found = range.createTextFinder(text)
    .findAll();

  let locations = [];

  for(let i = 0; i < found.length; i++){

    const cell = found[i];

    locations.push(cell.getA1Notation())


    if( i === position) break;
  
  }

  return locations;

}

/**

* Finds the first set of matching cells of n in length or less.

* @param {string} sheetName - the name of the sheet tab.

* @param {string|number} text - text to search.

* @param {number} n - the max number of items to report.

* @param {string} rangeLoc - A1- Notation of selected range.

* @return {array} - Array of cell positions of the found match.

function test_v2(sheetName, text, n, rangeLoc){

const position = n - 1;

const ss = SpreadsheetApp.getActiveSpreadsheet();

const sheet = ss.getSheetByName(sheetName);

const range = sheet.getRange(rangeLoc)

const found = range.createTextFinder(text)

.findAll();

let locations = [];

for(let i = 0; i < found.length; i++){

const cell = found[i];

locations.push(cell.getA1Notation())

if( i === position) break;

}

return locations;

}

test_v3 – Google Apps Script Text Finder Class- findNext()

Code breakdown can be found here: link.

In this function, a call is made to the spreadsheet to retrieve the found cell value each time findNext() method of the Text Finder Class is called. On each iteration, the getA1Notation method is used to retrieve the cell location. This location is then stored as an array value in the locations variable before being returned to the initiating function.

The function used a while-loop to iterate through each next item found until the counter – or the number of required cells to collect – is reached.

/**
 * Finds the first set of matching cells of n in length or less.
 * @param {string} sheetName - the name of the sheet tab. 
 * @param {string|number} text - text to search. 
 * @param {number} n - the max number of items to report.
 * @param {string} rangeLoc - A1- Notation of selected range.
 * @return {array} - Array of cell positions of the found match.
 */
function test_v3(sheetName, text, n, rangeLoc){


  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(sheetName);
  const range = sheet.getRange(rangeLoc)

  const finder = range.createTextFinder(text)

  let locations = [];
  let counter = n;

  while(counter > 0){
    
    let found = "";

      found = finder
        .findNext()
        .getA1Notation();

    locations.push(found);

    --counter;
  };


  return locations

};

/**

* Finds the first set of matching cells of n in length or less.

* @param {string} sheetName - the name of the sheet tab.

* @param {string|number} text - text to search.

* @param {number} n - the max number of items to report.

* @param {string} rangeLoc - A1- Notation of selected range.

* @return {array} - Array of cell positions of the found match.

function test_v3(sheetName, text, n, rangeLoc){

const ss = SpreadsheetApp.getActiveSpreadsheet();

const sheet = ss.getSheetByName(sheetName);

const range = sheet.getRange(rangeLoc)

const finder = range.createTextFinder(text)

let locations = [];

let counter = n;

while(counter > 0){

let found = "";

found = finder

.findNext()

.getA1Notation();

locations.push(found);

--counter;

};

return locations

};

Results & Discussion

Analysis of Google Apps Script Create Finder Class Retrieve n found values — Performance in Milliseconds to Retrieve the first 10 or 50 Matching Values over a 50,000 Row Range Contain Either 1000 or 100 Matchable items Using the Google Apps Script Spreadsheet App Finder Class.

Test 1: Retrieve the first 10 cells containing the search text where the range contains 1,000 matching search items.

Version 3 –findNext() performed better on average when there were 1000 potential items to find in the range but only the first 10 items need to be selected. Versions 3’s average speed was 1368.45ms compared to version 2’s average run speed of 1826.24ms. This is a performance increase of 257.79ms for version 3.

Version 2’s lower performance is likely due to needing to collect all available found cells before it can extract the top 10 items.

Version 3, makes 10 calls to the Google Sheets in this example. Compared to version 2, this takes relatively less time than collecting all available found cell references to the search item.

TEST 1: 1,000 randomised items to find in 50,000. Return first 10 matches using v2-findAll and v3-findNext functions.

Test 2: Retrieve the first 50 cells containing the search text where the range contains 1,000 matching search items.

Version 2 – findAll() performed significantly better over 100 runs than version 3 when retrieving the top 50 found cells from a possible 1000. Version 2 was, on average, 4993.61ms faster at an average runtime of 1578.19ms compared to version 3’s sluggish 6571.80ms average.

It was expected that test one and test two’s times for version 2 would be similar and there are only 48.05ms between their average runtimes.

Version 3’s poor performance is likely due to its reliance on calling the spreadsheet to collect the cell data on all 50 calls it needs to make.

TEST 2: 1,000 randomised items to find in 50,000. Return first 50 matches using v2-findAll and v3-findNext functions.

Test 3: Retrieve the first 10 cells containing the search text where the range contains 100 matching search items.

Version 2, again, performed better by 975.16ms than version 3 when there was a smaller potential number of items to find in the range and only the first ten items need to be retrieved.

Here the performance margin between the two versions was closer than in the previous test. Version 2’s average run speed was 360.94ms while version 3’s runtime was 1336.10ms.

With a smaller number of retrieved items, the version 2 findAll() function did not have to work as hard to collect the methods related to each range it collects. Whereas version 3 still needed to make 10 performance-intensive calls back to the Google Sheet each time with relatively no performance change to test one.

TEST 3: 100 randomised items to find in 50,000. Return first 10 matches using v2-findAll and v3-findNext functions.

Test 4: Retrieve the first 50 cells containing the search text where the range contains 100 matching search items.

Predictably, version 2 – findAll() performed the best when the expected match sample is small (100 available matches) and the total first set of cells to retrieve was relatively large (50).

Version 2’s average completion time was 377.13ms compared to version 3’s average of 6552.72ms, performing on average 6175.59ms faster. This is by far the largest margin on performance between the two versions.

Here again, version 3 must perform 50 calls to the Google Sheet, each one retrieving the cell range data. Alternatively, version 2 makes one call to the spreadsheet and then retrieves the cell data for all collected values. This is significantly faster than version 3’s approach.

TEST 4: 100 randomised items to find in 50,000. Return first 50 matches using v2-findAll and v3-findNext functions.

Overall

On datasets that may have the potential to contain a large number of matching items, but fewer required results to return, version 3 may be the best option. In all other cases, version 2 is the most optimal approach to finding data in a range.

It is important to note that it can be difficult to accurately measure performance with Apps Script runs because resource allocation to run a script does seem to vary. Nevertheless, with a sample size of 100 runs, it is hoped that average values will be more accurate than a smaller sample.

Grab Your Own Copy of the Google Sheet and Attached Code here

If you have found the tutorial helpful, why not shout me a coffee ☕? I'd really appreciate it.

Need help with Google Workspace development?

Go something to solve bigger than Chat GPT?

Schedule a free consultation today to discuss your needs and get started or learn more about our services here.

~Yagi

The Code: Range_ConditionalFormatting()

Class

Methods

clearRule(rangeOrRanges, [clearType])

Parameters

Clear types

Examples

clearRule(range) – Single range and no optional clear type

clearRule(ranges) – Multiple ranges and no optional clear type

clearRule(range, clearType = 0) – Single range with clear type zero- Exact match

clearRule(ranges, clearType = 0) – Multiple ranges with clear type zero – Exact match

clearRule(range, clearType = 1) – Single range with clear type one – Within range

clearRule(ranges, clearType = 1) – Multiple ranges with clear type zero- Within range

clearRule(range, clearType = 2) – Single range with clear type one – Overlaps

clearRule(ranges, clearType = 2) – Multiple ranges with clear type zero- Overlaps

setRule(rules, [position])

Parameters

Examples

Video Tutorial Series

Conclusion

Share this:

Like this:

Share this:

Like this:

Share this:

Like this:

Sort Tabs in Google Sheets – Video

The Code

Code Breakdown

onOpen()

The Sheet Tab Sorter object

Ascending and Descending Property Methods

The sort Google Sheet Tabs machine (sortTabs)

Get a list of sheets

Using Intl Collator for natural sorting

Sort Google Sheet tabs Apps Script-side

Reversing the sort

Updating the Google Sheet tabs to the desired order

Starting the sort after a set number of tabs

Google Sheet Tabs by Date

Changelog

Share this:

Like this:

Method

Sample Data

Test

Code

Main Test RUN

test_v2 – Google Apps Script Text Finder Class- findAll()

test_v3 – Google Apps Script Text Finder Class- findNext()

Results & Discussion

Test 1: Retrieve the first 10 cells containing the search text where the range contains 1,000 matching search items.

Test 2: Retrieve the first 50 cells containing the search text where the range contains 1,000 matching search items.

Test 3: Retrieve the first 10 cells containing the search text where the range contains 100 matching search items.

Test 4: Retrieve the first 50 cells containing the search text where the range contains 100 matching search items.

Overall

Share this:

Like this: