Code - Yagisanatode

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.

Table of Contents

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.

A custom-build HTML Time Input Element

Recently while working on a project, I found that the standard HTML Time Input field (see below) wasn’t sufficient for my needs.

<input type="time" id="setTime" name="setTime" />

Standard HTML time input field

I needed users to be able to input 24hr time right down to the milliseconds. Something like this:

Table of Contents

Features

Mobile Input will display the number pad

Under the hood, each input field is a number. This means that mobile devices should default to the number pad for convenience.

Value retrieval

Values are stored under the name time-<<timeType>> , for example time-hours.

You can loop over your form data and retrieve the names as needed or set a custom ID to the field as you create it dynamically with JavaScript. You can see an example of this in the Example 1: Single time field section.

Automatically moves to the next input

Setting field character limitsSetting character limits on each time field allows the cursor to automatically move to the next fields.

Client-Side Validation

Removing ‘Accepted’ number input characters that are not numbers

Yeah, yeah, you know you got to validate server-side too, but it’s good to let the user know that if they accidentally put in an accepted number character like e, +, - that it will be removed for them automatically.

Cannot exceed the number range

The max and min number ranges are set by default, but you can always change them manually.

Maybe you want to start with minutes, but as a duration and not a time, have minutes that go all the way up to 10,000. All good, just change the max value in the time-minute number input.

If a user puts in a number greater or less than the default min or max, the number will be replaced by the min or max respectively.

So for example, if the user sets 69 (hur hur hur) minutes but the max minutes is 60 then the field will default to 60.

Likewise, if the user sets the millisecond cell to 2 but your min is 500, then it will default to 500 milliseconds.

This is done with some JavaScript event listeners.

Returning back a tab will clear the field

Returning back a tab by cursor or shift-tab will clear out the field for the user to start afresh.

Prepends Zeros (0) to Any Number Not At Max Character Length

This is just an aesthetic thing, but it makes a difference. When a number’s character length is less than the maximum character length, then additional zeroes will be added to the front of the number.

Quickly add or remove a time input

The values of the time inputs are formatted using a generated CSS method for number inputs within the timeInput class. Further event listeners are looped over this class to allow for fewer or greater number-input elements.

As such, you can add days, months and years or, nanoseconds, microseconds and zeptoseconds. Alternatively, you could remove one of the existing time measures from the field.

The Code for the Custom Time Input field

You can grab a basic sample of the code here:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!--     For the tutorial: A Custom-Built HTML Time Input Element
    https://yagisanatode.com/a-custom-build-html-time-input-element/ -->
    <title>Time</title>
</head>

<body>
    <style>
        .timeInput {
            display: grid;
            grid-template-columns: repeat(7, auto);
            width: 8.5em;

        }

        .timeInput input::-webkit-outer-spin-button,
        .timeInput input::-webkit-inner-spin-button {
            display: none;
            margin: 0;
        }

        .timeInput .time-lables {
            font-size: x-small;
            text-align: center;
        }

        .timeInput .time-hours {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-minutes {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-seconds {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-milliseconds {
            width: 2.7em;
            text-align: center;
        }
    </style>
    <div class="timeInput">
        <span class="time-lables">HH</span>
        <span class="time-lables"></span>
        <span class="time-lables">MM</span>
        <span class="time-lables"></span>
        <span class="time-lables">SS</span>
        <span class="time-lables"></span>
        <span class="time-lables">MS</span>
        <input class="time-hours" type="number" name="time-hours" min=0 max=24 step=1 placeholder="00" data-maxlen=2>
        <span>:</span>
        <input class="time-minutes" type="number" name="time-minutes" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
        <span>:</span>
        <input class="time-seconds" type="number" name="time-seconds" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
        <span>:</span>
        <input class="time-milliseconds" type="number" name="time-milliseconds" min=0 max=999 step=1 placeholder="000"
            data-maxlen=4>
    </div>
    <br>
    <br>
    <br>
    <input type="time" id="setTime" name="setTime" />

    <script type="text/javascript">

        /**
         * Handles the time values for the timeInput element.
         * - Provides validation
         * -- Only numbers
         * -- witin min and max
         * -- max length
         * - Moves cursor to next input after max length is exceeded.
         */
        function customTimeHandler() {

            /**
             * Validates the input value.
             * @param {HTMLElement} input
             */
            function validate(input) {
                let val = input.value

                // Check for non numbers & remove
                val = val.replaceAll(/\D/g, "")

                // If greater than data-maxlen, remove last char
                val = val.substring(0, input.dataset.maxlen)

                const valNum = Number(val)

                // If greater than max, set max
                if (valNum < input.min) {
                    val = input.min
                }
                // If less than min, set min
                else if (valNum > input.max) {
                    val = input.max
                }
                // If less than total number of chars in the placeholder add leading zero
                const placeholderZeroes = input.placeholder
                const charLenMax = 10 ** (input.placeholder.length - 1)

                if (valNum == 0) {
                    val = placeholderZeroes
                }
                else if (valNum < charLenMax) {
                    const lenDif = placeholderZeroes.length + 1 - val.length
                    const addedZeros = placeholderZeroes.substring(1, lenDif)

                    val = addedZeros + val
                }

                input.value = val
            }

            const timeInputElements = document.querySelectorAll(".timeInput")


            timeInputElements.forEach(timeInputEl => {

                const timeInputs = timeInputEl.querySelectorAll('input')

                timeInputs.forEach((input, idx) => {


                    input.addEventListener('focus', function() {
                        input.value = ""
                    })

                    input.addEventListener('input', function() {
                        const inputLen = input.value.length
                        const maxLen = input.dataset.maxlen

                        if (inputLen >= maxLen) {

                            validate(input)
                            if (idx < timeInputs.length - 1) {

                                timeInputs[idx + 1].focus()
                            }
                        }
                    })

                    input.addEventListener('focusout', function() {
                        validate(input)
                    })

                })

            })
        }

        customTimeHandler()
    </script>


</body>

</html>

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

<!DOCTYPE html>

<html>

<head>

<!-- For the tutorial: A Custom-Built HTML Time Input Element

https://yagisanatode.com/a-custom-build-html-time-input-element/ -->

</head>

<body>

<style>

.timeInput {

display: grid;

grid-template-columns: repeat(7, auto);

width: 8.5em;

}

.timeInput input::-webkit-outer-spin-button,

.timeInput input::-webkit-inner-spin-button {

display: none;

margin: 0;

}

.timeInput .time-lables {

font-size: x-small;

text-align: center;

}

.timeInput .time-hours {

width: 1.2em;

text-align: center;

}

.timeInput .time-minutes {

width: 1.2em;

text-align: center;

}

.timeInput .time-seconds {

width: 1.2em;

text-align: center;

}

.timeInput .time-milliseconds {

width: 2.7em;

text-align: center;

}

</style>

<input class="time-milliseconds" type="number" name="time-milliseconds" min=0 max=999 step=1 placeholder="000"

data-maxlen=4>

</div>

<br>

/**

* Handles the time values for the timeInput element.

* - Provides validation

* -- Only numbers

* -- witin min and max

* -- max length

* - Moves cursor to next input after max length is exceeded.

function customTimeHandler() {

/**

* Validates the input value.

* @param {HTMLElement} input

function validate(input) {

let val = input.value

// Check for non numbers & remove

val = val.replaceAll(/\D/g, "")

// If greater than data-maxlen, remove last char

val = val.substring(0, input.dataset.maxlen)

const valNum = Number(val)

// If greater than max, set max

if (valNum < input.min) {

val = input.min

}

// If less than min, set min

else if (valNum > input.max) {

val = input.max

}

// If less than total number of chars in the placeholder add leading zero

const placeholderZeroes = input.placeholder

const charLenMax = 10 ** (input.placeholder.length - 1)

if (valNum == 0) {

val = placeholderZeroes

}

else if (valNum < charLenMax) {

const lenDif = placeholderZeroes.length + 1 - val.length

const addedZeros = placeholderZeroes.substring(1, lenDif)

val = addedZeros + val

}

input.value = val

}

const timeInputElements = document.querySelectorAll(".timeInput")

timeInputElements.forEach(timeInputEl => {

const timeInputs = timeInputEl.querySelectorAll('input')

timeInputs.forEach((input, idx) => {

input.addEventListener('focus', function() {

input.value = ""

})

input.addEventListener('input', function() {

const inputLen = input.value.length

const maxLen = input.dataset.maxlen

if (inputLen >= maxLen) {

validate(input)

if (idx < timeInputs.length - 1) {

timeInputs[idx + 1].focus()

}

})

input.addEventListener('focusout', function() {

validate(input)

})

}

customTimeHandler()

</script>

</body>

</html>

Example 1: Single time field

In this simple example, we will encapsulate the time input into a form and add a ‘submit’ button. Of course, you can add other form elements to the form as well.

In our script section, we added two functions submitForm() and getFormData() that is called on submit and retrieve all values in the form by their ‘name’ attribute.

I’ve put the submit button outside the form so you can see the logged results. If you wish to refresh the page or move to another page you can add the submit button inside the form.

Custom HTML Time Input Field inside a form with logged values

Check out the updated code:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!--     For the tutorial: A Custom-Built HTML Time Input Element
    https://yagisanatode.com/a-custom-build-html-time-input-element/ -->
    <title>Time</title>
</head>

<body>
    <style>
        .timeInput {
            display: grid;
            grid-template-columns: repeat(7, auto);
            width: 8.0em;

        }

        .timeInput input::-webkit-outer-spin-button,
        .timeInput input::-webkit-inner-spin-button {
            display: none;
            margin: 0;
        }

        .timeInput .time-lables {
            font-size: x-small;
            text-align: center;
        }

        .timeInput .time-hours {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-minutes {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-seconds {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-milliseconds {
            width: 2em;
            text-align: center;
        }
    </style>
    <form id="inputForm">
        <div class="timeInput">
            <span class="time-lables">HH</span>
            <span class="time-lables"></span>
            <span class="time-lables">MM</span>
            <span class="time-lables"></span>
            <span class="time-lables">SS</span>
            <span class="time-lables"></span>
            <span class="time-lables">MS</span>
            <input class="time-hours" type="number" name="time-hours" min=0 max=24 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-minutes" type="number" name="time-minutes" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-seconds" type="number" name="time-seconds" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-milliseconds" type="number" name="time-milliseconds" min=0 max=999 step=1 placeholder="000"
                data-maxlen=4>
        </div>
        <hr>
    </form>
        <button onclick="submitForm()">Submit</button>          



    <script type="text/javascript">

        /**
         * Handles the time values for the timeInput element.
         * - Provides validation
         * -- Only numbers
         * -- witin min and max
         * -- max length
         * - Moves cursor to next input after max length is exceeded.
         */
        function customTimeHandler() {

            /**
             * Validates the input value.
             * @param {HTMLElement} input
             */
            function validate(input) {
                let val = input.value

                // Check for non numbers & remove
                val = val.replaceAll(/\D/g, "")

                // If greater than data-maxlen, remove last char
                val = val.substring(0, input.dataset.maxlen)

                const valNum = Number(val)

                // If greater than max, set max
                if (valNum < input.min) {
                    val = input.min
                }
                // If less than min, set min
                else if (valNum > input.max) {
                    val = input.max
                }
                // If less than total number of chars in the placeholder add leading zero
                const placeholderZeroes = input.placeholder
                const charLenMax = 10 ** (input.placeholder.length - 1)

                if (valNum == 0) {
                    val = placeholderZeroes
                }
                else if (valNum < charLenMax) {
                    const lenDif = placeholderZeroes.length + 1 - val.length
                    const addedZeros = placeholderZeroes.substring(1, lenDif)

                    val = addedZeros + val
                }

                input.value = val
            }

            const timeInputElements = document.querySelectorAll(".timeInput")


            timeInputElements.forEach(timeInputEl => {

                const timeInputs = timeInputEl.querySelectorAll('input')

                timeInputs.forEach((input, idx) => {


                    input.addEventListener('focus', function() {
                        input.value = ""
                    })

                    input.addEventListener('input', function() {
                        const inputLen = input.value.length
                        const maxLen = input.dataset.maxlen

                        if (inputLen >= maxLen) {

                            validate(input)
                            if (idx < timeInputs.length - 1) {

                                timeInputs[idx + 1].focus()
                            }
                        }
                    })

                    input.addEventListener('focusout', function() {
                        validate(input)
                    })

                })

            })
        }

        customTimeHandler()

        /**
         * ##### SUBMIT FORM #####
         * 
         */

        // Function to handle form submission
        function submitForm() {
            const form = document.getElementById('inputForm');


            const data = getFormData(form)


            console.log(data)
            // Send the data back serverside.
        }

        // Function to collect form data into an object
        function getFormData(form) {
            let formData = {};

            for (let i = 0; i < form.elements.length; i++) {
                const element = form.elements[i];
                if (element.name) {

                    if (element.type === "checkbox" || element.type === "radio") {
                        formData[element.name] = element.checked;
                    } else {
                        formData[element.name] = element.value;
                    }
                }
            }
            return formData;
        }


    </script>


</body>

</html>

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

<!DOCTYPE html>

<html>

<head>

<!-- For the tutorial: A Custom-Built HTML Time Input Element

https://yagisanatode.com/a-custom-build-html-time-input-element/ -->

</head>

<body>

<style>

.timeInput {

display: grid;

grid-template-columns: repeat(7, auto);

width: 8.0em;

}

.timeInput input::-webkit-outer-spin-button,

.timeInput input::-webkit-inner-spin-button {

display: none;

margin: 0;

}

.timeInput .time-lables {

font-size: x-small;

text-align: center;

}

.timeInput .time-hours {

width: 1.2em;

text-align: center;

}

.timeInput .time-minutes {

width: 1.2em;

text-align: center;

}

.timeInput .time-seconds {

width: 1.2em;

text-align: center;

}

.timeInput .time-milliseconds {

width: 2em;

text-align: center;

}

</style>

<input class="time-milliseconds" type="number" name="time-milliseconds" min=0 max=999 step=1 placeholder="000"

data-maxlen=4>

</div>

<hr>

</form>

<button onclick="submitForm()">Submit</button>

/**

* Handles the time values for the timeInput element.

* - Provides validation

* -- Only numbers

* -- witin min and max

* -- max length

* - Moves cursor to next input after max length is exceeded.

function customTimeHandler() {

/**

* Validates the input value.

* @param {HTMLElement} input

function validate(input) {

let val = input.value

// Check for non numbers & remove

val = val.replaceAll(/\D/g, "")

// If greater than data-maxlen, remove last char

val = val.substring(0, input.dataset.maxlen)

const valNum = Number(val)

// If greater than max, set max

if (valNum < input.min) {

val = input.min

}

// If less than min, set min

else if (valNum > input.max) {

val = input.max

}

// If less than total number of chars in the placeholder add leading zero

const placeholderZeroes = input.placeholder

const charLenMax = 10 ** (input.placeholder.length - 1)

if (valNum == 0) {

val = placeholderZeroes

}

else if (valNum < charLenMax) {

const lenDif = placeholderZeroes.length + 1 - val.length

const addedZeros = placeholderZeroes.substring(1, lenDif)

val = addedZeros + val

}

input.value = val

}

const timeInputElements = document.querySelectorAll(".timeInput")

timeInputElements.forEach(timeInputEl => {

const timeInputs = timeInputEl.querySelectorAll('input')

timeInputs.forEach((input, idx) => {

input.addEventListener('focus', function() {

input.value = ""

})

input.addEventListener('input', function() {

const inputLen = input.value.length

const maxLen = input.dataset.maxlen

if (inputLen >= maxLen) {

validate(input)

if (idx < timeInputs.length - 1) {

timeInputs[idx + 1].focus()

}

})

input.addEventListener('focusout', function() {

validate(input)

})

}

customTimeHandler()

/**

* ##### SUBMIT FORM #####

// Function to handle form submission

function submitForm() {

const form = document.getElementById('inputForm');

const data = getFormData(form)

console.log(data)

// Send the data back serverside.

}

// Function to collect form data into an object

function getFormData(form) {

let formData = {};

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

const element = form.elements[i];

if (element.name) {

if (element.type === "checkbox" || element.type === "radio") {

formData[element.name] = element.checked;

} else {

formData[element.name] = element.value;

}

return formData;

}

</script>

</body>

</html>

Example 2: Multiple time fields

What if we want to have multiple instances of the custom time input in our HTML?

In this example, we will have a start and end time. Notice that we will need to change the name each time slightly so that the value is stored.

As such, in the example we append -start and -end to the input fields.

Yeap, that’s all you need to do.

Multiple Custom HTML Time Input Fields inside a form with logged values

Check out the updated code:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!--     For the tutorial: A Custom-Built HTML Time Input Element
    https://yagisanatode.com/a-custom-build-html-time-input-element/ -->
    <title>Time</title>
</head>

<body>
    <style>
        .timeInput {
            display: grid;
            grid-template-columns: repeat(7, auto);
            width: 8.0em;

        }

        .timeInput input::-webkit-outer-spin-button,
        .timeInput input::-webkit-inner-spin-button {
            display: none;
            margin: 0;
        }

        .timeInput .time-lables {
            font-size: x-small;
            text-align: center;
        }

        .timeInput .time-hours {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-minutes {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-seconds {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-milliseconds {
            width: 2em;
            text-align: center;
        }
    </style>
    <form id="inputForm">
        <div>Start Time</div>
        <div class="timeInput">
            <span class="time-lables">HH</span>
            <span class="time-lables"></span>
            <span class="time-lables">MM</span>
            <span class="time-lables"></span>
            <span class="time-lables">SS</span>
            <span class="time-lables"></span>
            <span class="time-lables">MS</span>
            <input class="time-hours" type="number" name="time-hours-start" min=0 max=24 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-minutes" type="number" name="time-minutes-start" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-seconds" type="number" name="time-seconds-start" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-milliseconds" type="number" name="time-milliseconds-start" min=0 max=999 step=1 placeholder="000"
                data-maxlen=4>
        </div>
        <hr>
        <div>Start Time</div>
        <div class="timeInput">
            <span class="time-lables">HH</span>
            <span class="time-lables"></span>
            <span class="time-lables">MM</span>
            <span class="time-lables"></span>
            <span class="time-lables">SS</span>
            <span class="time-lables"></span>
            <span class="time-lables">MS</span>
            <input class="time-hours" type="number" name="time-hours-end" min=0 max=24 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-minutes" type="number" name="time-minutes-end" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-seconds" type="number" name="time-seconds-end" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
            <span>:</span>
            <input class="time-milliseconds" type="number" name="time-milliseconds-end" min=0 max=999 step=1 placeholder="000"
                data-maxlen=4>
        </div>
        <hr>
    </form>
        <button onclick="submitForm()">Submit</button>          



    <script type="text/javascript">

        /**
         * Handles the time values for the timeInput element.
         * - Provides validation
         * -- Only numbers
         * -- witin min and max
         * -- max length
         * - Moves cursor to next input after max length is exceeded.
         */
        function customTimeHandler() {

            /**
             * Validates the input value.
             * @param {HTMLElement} input
             */
            function validate(input) {
                let val = input.value

                // Check for non numbers & remove
                val = val.replaceAll(/\D/g, "")

                // If greater than data-maxlen, remove last char
                val = val.substring(0, input.dataset.maxlen)

                const valNum = Number(val)

                // If greater than max, set max
                if (valNum < input.min) {
                    val = input.min
                }
                // If less than min, set min
                else if (valNum > input.max) {
                    val = input.max
                }
                // If less than total number of chars in the placeholder add leading zero
                const placeholderZeroes = input.placeholder
                const charLenMax = 10 ** (input.placeholder.length - 1)

                if (valNum == 0) {
                    val = placeholderZeroes
                }
                else if (valNum < charLenMax) {
                    const lenDif = placeholderZeroes.length + 1 - val.length
                    const addedZeros = placeholderZeroes.substring(1, lenDif)

                    val = addedZeros + val
                }

                input.value = val
            }

            const timeInputElements = document.querySelectorAll(".timeInput")


            timeInputElements.forEach(timeInputEl => {

                const timeInputs = timeInputEl.querySelectorAll('input')

                timeInputs.forEach((input, idx) => {


                    input.addEventListener('focus', function() {
                        input.value = ""
                    })

                    input.addEventListener('input', function() {
                        const inputLen = input.value.length
                        const maxLen = input.dataset.maxlen

                        if (inputLen >= maxLen) {

                            validate(input)
                            if (idx < timeInputs.length - 1) {

                                timeInputs[idx + 1].focus()
                            }
                        }
                    })

                    input.addEventListener('focusout', function() {
                        validate(input)
                    })

                })

            })
        }

        customTimeHandler()

        /**
         * ##### SUBMIT FORM #####
         * 
         */

        // Function to handle form submission
        function submitForm() {
            const form = document.getElementById('inputForm');


            const data = getFormData(form)


            console.log(data)
            // Send the data back serverside.
        }

        // Function to collect form data into an object
        function getFormData(form) {
            let formData = {};

            for (let i = 0; i < form.elements.length; i++) {
                const element = form.elements[i];
                if (element.name) {

                    if (element.type === "checkbox" || element.type === "radio") {
                        formData[element.name] = element.checked;
                    } else {
                        formData[element.name] = element.value;
                    }
                }
            }
            return formData;
        }


    </script>


</body>

</html>

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

<!DOCTYPE html>

<html>

<head>

<!-- For the tutorial: A Custom-Built HTML Time Input Element

https://yagisanatode.com/a-custom-build-html-time-input-element/ -->

</head>

<body>

<style>

.timeInput {

display: grid;

grid-template-columns: repeat(7, auto);

width: 8.0em;

}

.timeInput input::-webkit-outer-spin-button,

.timeInput input::-webkit-inner-spin-button {

display: none;

margin: 0;

}

.timeInput .time-lables {

font-size: x-small;

text-align: center;

}

.timeInput .time-hours {

width: 1.2em;

text-align: center;

}

.timeInput .time-minutes {

width: 1.2em;

text-align: center;

}

.timeInput .time-seconds {

width: 1.2em;

text-align: center;

}

.timeInput .time-milliseconds {

width: 2em;

text-align: center;

}

</style>

<div>Start Time</div>

<input class="time-milliseconds" type="number" name="time-milliseconds-start" min=0 max=999 step=1 placeholder="000"

data-maxlen=4>

</div>

<hr>

<div>Start Time</div>

<input class="time-milliseconds" type="number" name="time-milliseconds-end" min=0 max=999 step=1 placeholder="000"

data-maxlen=4>

</div>

<hr>

</form>

<button onclick="submitForm()">Submit</button>

/**

* Handles the time values for the timeInput element.

* - Provides validation

* -- Only numbers

* -- witin min and max

* -- max length

* - Moves cursor to next input after max length is exceeded.

function customTimeHandler() {

/**

* Validates the input value.

* @param {HTMLElement} input

function validate(input) {

let val = input.value

// Check for non numbers & remove

val = val.replaceAll(/\D/g, "")

// If greater than data-maxlen, remove last char

val = val.substring(0, input.dataset.maxlen)

const valNum = Number(val)

// If greater than max, set max

if (valNum < input.min) {

val = input.min

}

// If less than min, set min

else if (valNum > input.max) {

val = input.max

}

// If less than total number of chars in the placeholder add leading zero

const placeholderZeroes = input.placeholder

const charLenMax = 10 ** (input.placeholder.length - 1)

if (valNum == 0) {

val = placeholderZeroes

}

else if (valNum < charLenMax) {

const lenDif = placeholderZeroes.length + 1 - val.length

const addedZeros = placeholderZeroes.substring(1, lenDif)

val = addedZeros + val

}

input.value = val

}

const timeInputElements = document.querySelectorAll(".timeInput")

timeInputElements.forEach(timeInputEl => {

const timeInputs = timeInputEl.querySelectorAll('input')

timeInputs.forEach((input, idx) => {

input.addEventListener('focus', function() {

input.value = ""

})

input.addEventListener('input', function() {

const inputLen = input.value.length

const maxLen = input.dataset.maxlen

if (inputLen >= maxLen) {

validate(input)

if (idx < timeInputs.length - 1) {

timeInputs[idx + 1].focus()

}

})

input.addEventListener('focusout', function() {

validate(input)

})

}

customTimeHandler()

/**

* ##### SUBMIT FORM #####

// Function to handle form submission

function submitForm() {

const form = document.getElementById('inputForm');

const data = getFormData(form)

console.log(data)

// Send the data back serverside.

}

// Function to collect form data into an object

function getFormData(form) {

let formData = {};

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

const element = form.elements[i];

if (element.name) {

if (element.type === "checkbox" || element.type === "radio") {

formData[element.name] = element.checked;

} else {

formData[element.name] = element.value;

}

return formData;

}

</script>

</body>

</html>

Example 3: Build Multiple HTML Custom Time Input fields dynamically with JavaScript

In this final example, we want to dynamically create time input fields equal to the number of tests we have. We will do this with the createTimeHanlder() function.

Next, we will add the HTML for the custom time input into a template literal (A string with inputs) and then add a name and append a counter to the name tags of each number input element.

Dynamically create Multiple Custom HTML Time Input Fields inside a form with logged values

Here’s the updated code:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!--     For the tutorial: A Custom-Built HTML Time Input Element
    https://yagisanatode.com/a-custom-build-html-time-input-element/ -->
    <title>Time</title>
</head>

<body>
    <style>
        .timeInput {
            display: grid;
            grid-template-columns: repeat(7, auto);
            width: 8.0em;

        }

        .timeInput input::-webkit-outer-spin-button,
        .timeInput input::-webkit-inner-spin-button {
            display: none;
            margin: 0;
        }

        .timeInput .time-lables {
            font-size: x-small;
            text-align: center;
        }

        .timeInput .time-hours {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-minutes {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-seconds {
            width: 1.2em;
            text-align: center;
        }

        .timeInput .time-milliseconds {
            width: 2em;
            text-align: center;
        }
    </style>
    <form id="inputForm">
        <div id="target_timeInputs">
            

        </div>

    </form>
        <button onclick="submitForm()">Submit</button>          



    <script type="text/javascript">


        function createTimeFields(number){

            let htmlData = ""

            for(i= 0; i < number; i++){
                const num = i + 1

                const name = `Test ${num}`
                const appendName = `-${num}`

                const timeFields = `
            <div>${name}</div>
            <div class="timeInput">
                <span class="time-lables">HH</span>
                <span class="time-lables"></span>
                <span class="time-lables">MM</span>
                <span class="time-lables"></span>
                <span class="time-lables">SS</span>
                <span class="time-lables"></span>
                <span class="time-lables">MS</span>
                <input class="time-hours" type="number" name="time-hours${appendName}" min=0 max=24 step=1 placeholder="00" data-maxlen=2>
                <span>:</span>
                <input class="time-minutes" type="number" name="time-minutes${appendName}" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
                <span>:</span>
                <input class="time-seconds" type="number" name="time-seconds${appendName}" min=0 max=60 step=1 placeholder="00" data-maxlen=2>
                <span>:</span>
                <input class="time-milliseconds" type="number" name="time-milliseconds${appendName}" min=0 max=999 step=1 placeholder="000"
                    data-maxlen=4>
            </div>
            <hr>

                `   
                htmlData += timeFields

            }
                const targetElement = document.getElementById("target_timeInputs")
                targetElement.innerHTML = htmlData
                customTimeHandler()

        }
        createTimeFields(4)

        /**
         * Handles the time values for the timeInput element.
         * - Provides validation
         * -- Only numbers
         * -- witin min and max
         * -- max length
         * - Moves cursor to next input after max length is exceeded.
         */
        function customTimeHandler() {

            /**
             * Validates the input value.
             * @param {HTMLElement} input
             */
            function validate(input) {
                let val = input.value

                // Check for non numbers & remove
                val = val.replaceAll(/\D/g, "")

                // If greater than data-maxlen, remove last char
                val = val.substring(0, input.dataset.maxlen)

                const valNum = Number(val)

                // If greater than max, set max
                if (valNum < input.min) {
                    val = input.min
                }
                // If less than min, set min
                else if (valNum > input.max) {
                    val = input.max
                }
                // If less than total number of chars in the placeholder add leading zero
                const placeholderZeroes = input.placeholder
                const charLenMax = 10 ** (input.placeholder.length - 1)

                if (valNum == 0) {
                    val = placeholderZeroes
                }
                else if (valNum < charLenMax) {
                    const lenDif = placeholderZeroes.length + 1 - val.length
                    const addedZeros = placeholderZeroes.substring(1, lenDif)

                    val = addedZeros + val
                }

                input.value = val
            }

            const timeInputElements = document.querySelectorAll(".timeInput")


            timeInputElements.forEach(timeInputEl => {

                const timeInputs = timeInputEl.querySelectorAll('input')

                timeInputs.forEach((input, idx) => {


                    input.addEventListener('focus', function() {
                        input.value = ""
                    })

                    input.addEventListener('input', function() {
                        const inputLen = input.value.length
                        const maxLen = input.dataset.maxlen

                        if (inputLen >= maxLen) {

                            validate(input)
                            if (idx < timeInputs.length - 1) {

                                timeInputs[idx + 1].focus()
                            }
                        }
                    })

                    input.addEventListener('focusout', function() {
                        validate(input)
                    })

                })

            })
        }

        

        /**
         * ##### SUBMIT FORM #####
         * 
         */

        // Function to handle form submission
        function submitForm() {
            const form = document.getElementById('inputForm');


            const data = getFormData(form)


            console.log(data)
            // Send the data back serverside.
        }

        // Function to collect form data into an object
        function getFormData(form) {
            let formData = {};

            for (let i = 0; i < form.elements.length; i++) {
                const element = form.elements[i];
                if (element.name) {

                    if (element.type === "checkbox" || element.type === "radio") {
                        formData[element.name] = element.checked;
                    } else {
                        formData[element.name] = element.value;
                    }
                }
            }
            return formData;
        }


    </script>


</body>

</html>

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

<!DOCTYPE html>

<html>

<head>

<!-- For the tutorial: A Custom-Built HTML Time Input Element

https://yagisanatode.com/a-custom-build-html-time-input-element/ -->

</head>

<body>

<style>

.timeInput {

display: grid;

grid-template-columns: repeat(7, auto);

width: 8.0em;

}

.timeInput input::-webkit-outer-spin-button,

.timeInput input::-webkit-inner-spin-button {

display: none;

margin: 0;

}

.timeInput .time-lables {

font-size: x-small;

text-align: center;

}

.timeInput .time-hours {

width: 1.2em;

text-align: center;

}

.timeInput .time-minutes {

width: 1.2em;

text-align: center;

}

.timeInput .time-seconds {

width: 1.2em;

text-align: center;

}

.timeInput .time-milliseconds {

width: 2em;

text-align: center;

}

</style>

</div>

</form>

<button onclick="submitForm()">Submit</button>

function createTimeFields(number){

let htmlData = ""

for(i= 0; i < number; i++){

const num = i + 1

const name = `Test ${num}`

const appendName = `-${num}`

const timeFields = `

<input class="time-milliseconds" type="number" name="time-milliseconds${appendName}" min=0 max=999 step=1 placeholder="000"

data-maxlen=4>

</div>

<hr>

htmlData += timeFields

}

const targetElement = document.getElementById("target_timeInputs")

targetElement.innerHTML = htmlData

customTimeHandler()

}

createTimeFields(4)

/**

* Handles the time values for the timeInput element.

* - Provides validation

* -- Only numbers

* -- witin min and max

* -- max length

* - Moves cursor to next input after max length is exceeded.

function customTimeHandler() {

/**

* Validates the input value.

* @param {HTMLElement} input

function validate(input) {

let val = input.value

// Check for non numbers & remove

val = val.replaceAll(/\D/g, "")

// If greater than data-maxlen, remove last char

val = val.substring(0, input.dataset.maxlen)

const valNum = Number(val)

// If greater than max, set max

if (valNum < input.min) {

val = input.min

}

// If less than min, set min

else if (valNum > input.max) {

val = input.max

}

// If less than total number of chars in the placeholder add leading zero

const placeholderZeroes = input.placeholder

const charLenMax = 10 ** (input.placeholder.length - 1)

if (valNum == 0) {

val = placeholderZeroes

}

else if (valNum < charLenMax) {

const lenDif = placeholderZeroes.length + 1 - val.length

const addedZeros = placeholderZeroes.substring(1, lenDif)

val = addedZeros + val

}

input.value = val

}

const timeInputElements = document.querySelectorAll(".timeInput")

timeInputElements.forEach(timeInputEl => {

const timeInputs = timeInputEl.querySelectorAll('input')

timeInputs.forEach((input, idx) => {

input.addEventListener('focus', function() {

input.value = ""

})

input.addEventListener('input', function() {

const inputLen = input.value.length

const maxLen = input.dataset.maxlen

if (inputLen >= maxLen) {

validate(input)

if (idx < timeInputs.length - 1) {

timeInputs[idx + 1].focus()

}

})

input.addEventListener('focusout', function() {

validate(input)

})

}

/**

* ##### SUBMIT FORM #####

// Function to handle form submission

function submitForm() {

const form = document.getElementById('inputForm');

const data = getFormData(form)

console.log(data)

// Send the data back serverside.

}

// Function to collect form data into an object

function getFormData(form) {

let formData = {};

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

const element = form.elements[i];

if (element.name) {

if (element.type === "checkbox" || element.type === "radio") {

formData[element.name] = element.checked;

} else {

formData[element.name] = element.value;

}

return formData;

}

</script>

</body>

</html>

Conclusion

That’s it. I would love to hear how you used this in your own projects and what modifications you made. Let me know in the comments.

I am actually using this for a project for a Google Workspace Add-on using Google Apps Script along with an accompanying hosted private site using Golang, SQLite, temple and HTMX.

Have fun!

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

Setup Google Apps Script Word Completion in Sublime Text

When working on Google Apps Script projects locally with CLASP, it can be handy to have text completion for the Apps Script classes and methods.

I’m currently shopping for a new IDE or text editor (the developer’s existential crisis) and have decided to pick up Sublime Text again after a 9-year hiatus after a mediocre three-week trial of Neovim.

After a fresh install of Sublime Text 4 here is what I needed to do:

Table of Contents

Requirements

Sublime Text 4 … I mean… c’mon.
NPM to install CLASP and the text completion package.
CLASP – The command line Apps Script tool for local development.
Git (possibly) – If the TypeScript Sublime package is missing, you must install it via Git.

Setup

Google gracefully created a text completion package that uses Definitely Typed a TypeScript repository for type definitions that can be used with both TypeScript and vanilla JavaScript.

Install the TypeScript Package for Sublime Text

Check for the TypeScript Package

First, we check if the TypeScript package has been added to Sublime Text.

Select ctrl shift P (cmd ⌘ should replace ctrl for Apple) to get the Command Pallete and start typing: Package Control: List Packages and select it.

If the TypeScript package is present, move on to adding the Apps Script type package.

Add the TypeScript Package

Head back to the Command Pallete ( ctrl shift P ) and this time start typing Package Control: Install Package.

This will load the Sublime package. Search for ‘TypeScript’. The name must be exact. If it is in the package list (It wasn’t for me) install it and move on to adding the Apps Script type package installation.

If the package is not on the list we will need to use git to clone the package from the Windows GitHub repo for the TypeScrpt-Sublime-Plugin.

Linux

cd ~/.config/sublime-text-3
git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

1 2	cd ~/.config/sublime-text-3 git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

Windows

cd "%APPDATA%\Sublime Text 3\Packages"
git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

1 2	cd "%APPDATA%\Sublime Text 3\Packages" git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

Mac

cd ~/"Library/Application Support/Sublime Text 3/Packages"
git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

1 2	cd ~/"Library/Application Support/Sublime Text 3/Packages" git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

You may need to close and reopen Sublime Text to see the effects.

Install the Google Apps Script Type Package

In your terminal or shell, run the following:

npm install --save @types/google-apps-script

This will install the autocomplete types for all of the Google Apps Script Classes and Methods.

Testing the Google Apps Script text completion in Sublime Text

Go ahead and open Sublime Text and create a JavaSript *.js file or TypeScirpt *.ts file.

Navigating Autocomplete

Start typing a Google Apps Script class like SpreadsheetApp. You should see it appear in the list.

You can use the up-down (↑↓) arrow keys to navigate the list and enter to select the method or class.

Sublime 4 Google Apps Script Autocomplete selecting a method or class

Tooltips – Method argument instructions

Information for each method should appear as you enter the braces.

Hovering over the method or class will reveal similar information.

Alt , will open the tooltip when the cursor is within the parentheses of the method.

Look at Multiple Arguments or tooltips

When there are multiple argument types, then you can click on the number to select from the list of types.

Sublime 4 Google Apps Script Autocomplete multiple argument types selection

Or you can use the keyboard shortcuts:

Alt , – to open the tooltip if it is not available

Alt ↑ or Alt ↓ – to navigate to the next tooltip for the method.

Rename a Variable, Class or Function

Ctrl T Ctrl M – With your cursor over a variable, class, method or function you can rename it and all occurrences of it.

Formatting

You can also use the TypeScript plugin to format your document.

Ctrl T Ctrl F Formats the whole document

Ctrl T Ctrl F Formats the selection

Ctrl ; Formats the line

You can learn more shortcuts from the TypeScript Plugin for Sublime Text docs.

Getting *.gs files to display autocomplete

Sometimes we use the gs file ending for Google Apps Script files. To get these to autocomplete we need to pair them to either JavaScript or TypeScrit.

In Sublime Text first create any .gs file and ensure you are open in that file.

Then, go to View -> Syntax -> Open all with current extension as … .

Select either JavaScript or TypeScript.

Now, when you edit the file, the Apps Script autocomplete will work as expected.

Conclusion

I’m not sure if I am going to stick with Sublime Text, but it is like slipping on a comfy pair of shoes after such a long break from it, so who knows?

I’d love to hear in the comments if you have used Sublime Text recently or are even using it for your own Apps Script projects. What do you love and not so love about it?

Oh, by the way, I recently built a little CLI tool to help update multiple Google Apps Script projects from a single source project. If this interests you, you can check it out here:

CLASPALL – Update Multiple Apps Script Projects From a Single Source

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

~Yagi

CLASPALL – Update Multiple Apps Script Projects From a Single Source

CLASPALL is a command line app that runs with CLASP, allowing you to update multiple Google Apps Script projects from a single core project file.

When developing for clients I typically have 3 separate projects:

Development
Testing
Production

CLASPALL allows me to update my Testing and Production projects from my Development project with a single command in my terminal: CLASPALL.

Continue reading “CLASPALL – Update Multiple Apps Script Projects From a Single Source”

Extracting the Valid Workdays Between Two Dates in JavaScript

Given a start date, end date, weekends and, holidays we will extract the valid workdays between two dates in JavaScript in this tutorial.

Sometimes we need to work backward from a date range and extract all the valid workdays within that range. Of course, we will need to exclude holidays and also days off for this period too so it is not just a simple case of subtracting the end date from the start date and adding one.

The best way to illustrate what we want to accomplish is by sharing some example data.

If you are looking to get the end work date given a start date and number of workdays, check out this tutorial:

Calculate the Workday End Date in JavaScript

The Example

For our example, we will need to prepare a list of date ranges, holiday periods and weekly days off (weekends).

We’ll say for convenience that we will work Monday to Friday and take Saturday and Sunday off. In JavaScirpt-land weekdays are represented as zero-based numbers with the USA-style start of the week occurring on Sunday. In this case, Sunday is zero (0) and Saturday is (6).

Let’s add in some holidays to give ourselves a well-earned break:

15 Sep 2024
31 Oct 2024 🎃🦇👻
24 Dec 2024
25 Dec 2024
01 Jan 2025

This could also be drawn from a regional API that provides dates for holidays in your area.

Finally, we will provide a small sample list of date ranges that we can check, but keep in mind that you can iterate over a much larger list at relatively good speed here.

10 Sep 2024 – 23 Sep 2024.
26 Oct 2024 – 4 Nov 2024.
22 Dec 2025 – 16 Jan 2024.

The blue represents the actual workdays, while the white section indicates the actual date range. Orange bold and underlined days are holidays that don’t fall on weekends. Light red days are weekly days off (in our case, weekends).

Across the top of the dates are the days of the week as a JavaScript day running from 0 (Sunday) to 8 (Saturday).

The Video Tutorial

To the video tutorial

Releases 8 Oct 2024

The Code

// EXTRACT THE WORKDAYS BETWEEN TWO DATES

// Given a start date, end date, weekends and holidays, extract the valid workdays between two dates. 


/**
 * Gets an array of workdays between two dates.
 * @param {Object} workperiod
 * @param {String} workperiod.startDate - Target date as valid JS date-string
 * @param {String} workperiod.endDate - Number of workdays. 
 * @param {Number[]} weekends - Array of days off as JS day of week. Sunday = 0, Saturday = 6
 * @param {String[]} holdays - Array of hoidays as JS-valid date-strings
 * @returns {Date[][]} Array of valid workdays.
 */
function getWorkdays(workperiod, weekends, holidays){
    const dayMilliseconds = 24 * 60 * 60 * 1000
    /**
     * Gets the UTC for current day.
     * @param {Sting} date 
     * @returns {Number} UTC Date in milliseconds
     */
    function getUTC(date){
        const dt = new Date(date)
        return Date.UTC(
            dt.getFullYear(),
            dt.getMonth(),
            dt.getDate()
        )
    }
    
    // Convert holidays of day of year as number. 
    const holidayUTC = holidays.map(holiday => getUTC(holiday))

    // Iterate over each date
    let workdays = workperiod.map(workday => {
        // -- Get day of year as number.
        const dayStart = getUTC(workday.startDate)
        const dayEnd   = getUTC(workday.endDate)

        // Get day of week
        let dayOfWeek = new Date(workday.startDate).getDay() 
        let day = dayStart

        let validWorkday = []
    
        while(day <= dayEnd){

            // Check if not weekends or holidays
            if(!weekends.includes(dayOfWeek) && !holidayUTC.includes(day)){
                const dt = new Date(day).toISOString().substring(0, 10)
                validWorkday.push(dt)
            }      

            day += dayMilliseconds
            dayOfWeek = dayOfWeek + 1 == 7? 0 : dayOfWeek + 1
        }

        return validWorkday

    })

    return workdays
}



/**
 * Main run test function
 */
function runsies(){
    // #### SAMPLE DATA 

    // HOLIDAYS
    const holidays = ["2024-09-15","2024-10-31","2024-12-24","2024-12-25","2025-01-01"]

    // DAYS OFF      [Sun: 0, Sat: 6] <- JavaScript Day of Week Standard.
    const weekends = [0, 6]

    const testRanges = [
        {
            startDate: '2024-09-10',
            endDate: '2024-09-23'
        },
        {
            startDate: '2024-10-26',
            endDate: '2024-11-04'
        },
        {
            startDate: '2024-12-22',
            endDate: '2025-01-16'
        },
    ]

    const respArray = getWorkdays(testRanges, weekends, holidays)

    testRanges.map((testRange, idx) => {
        testRange.validDays = respArray[idx]
        testRange.count = respArray[idx].length
    
        return testRange
    })
    
    console.log(JSON.stringify(testRanges,null, " "))

}

runsies()

100

101

102

103

104

105

106

107

// EXTRACT THE WORKDAYS BETWEEN TWO DATES

// Given a start date, end date, weekends and holidays, extract the valid workdays between two dates.

/**

* Gets an array of workdays between two dates.

* @param {Object} workperiod

* @param {String} workperiod.startDate - Target date as valid JS date-string

* @param {String} workperiod.endDate - Number of workdays.

* @param {Number[]} weekends - Array of days off as JS day of week. Sunday = 0, Saturday = 6

* @param {String[]} holdays - Array of hoidays as JS-valid date-strings

* @returns {Date[][]} Array of valid workdays.

function getWorkdays(workperiod, weekends, holidays){

const dayMilliseconds = 24 * 60 * 60 * 1000

/**

* Gets the UTC for current day.

* @param {Sting} date

* @returns {Number} UTC Date in milliseconds

function getUTC(date){

const dt = new Date(date)

return Date.UTC(

dt.getFullYear(),

dt.getMonth(),

dt.getDate()

)

}

// Convert holidays of day of year as number.

const holidayUTC = holidays.map(holiday => getUTC(holiday))

// Iterate over each date

let workdays = workperiod.map(workday => {

// -- Get day of year as number.

const dayStart = getUTC(workday.startDate)

const dayEnd = getUTC(workday.endDate)

// Get day of week

let dayOfWeek = new Date(workday.startDate).getDay()

let day = dayStart

let validWorkday = []

while(day <= dayEnd){

// Check if not weekends or holidays

if(!weekends.includes(dayOfWeek) && !holidayUTC.includes(day)){

const dt = new Date(day).toISOString().substring(0, 10)

validWorkday.push(dt)

}

day += dayMilliseconds

dayOfWeek = dayOfWeek + 1 == 7? 0 : dayOfWeek + 1

}

return validWorkday

})

return workdays

}

/**

* Main run test function

function runsies(){

// #### SAMPLE DATA

// HOLIDAYS

const holidays = ["2024-09-15","2024-10-31","2024-12-24","2024-12-25","2025-01-01"]

// DAYS OFF [Sun: 0, Sat: 6] <- JavaScript Day of Week Standard.

const weekends = [0, 6]

const testRanges = [

{

startDate: '2024-09-10',

endDate: '2024-09-23'

{

startDate: '2024-10-26',

endDate: '2024-11-04'

{

startDate: '2024-12-22',

endDate: '2025-01-16'

]

const respArray = getWorkdays(testRanges, weekends, holidays)

testRanges.map((testRange, idx) => {

testRange.validDays = respArray[idx]

testRange.count = respArray[idx].length

return testRange

})

console.log(JSON.stringify(testRanges,null, " "))

}

runsies()

The runsies() function

The runsies() function is the main test function. It contains the 3 different variables that we will send to the getWorkdays() function to generate our list of days.

We’re using the year-month-date (YYYY-MM-DD) format favoured by computer nerds like me.

Once we get the list of days back from the getWordays() function we will then map our existing testRanges array of objects and add the valid days as a property and the total count of valid days.

Finally, we will stringify the array object to make it pretty for logging.

You Are Looking So Fine Loki GIFfrom You Are Looking So Fine GIFs

Running the script will display these results:

[
 {
  "startDate": "2024-09-10",
  "endDate": "2024-09-23",
  "validDays": [
   "2024-09-10",
   "2024-09-11",
   "2024-09-12",
   "2024-09-13",
   "2024-09-16",
   "2024-09-17",
   "2024-09-18",
   "2024-09-19",
   "2024-09-20",
   "2024-09-23"
  ],
  "count": 10
 },
 {
  "startDate": "2024-10-26",
  "endDate": "2024-11-04",
  "validDays": [
   "2024-10-28",
   "2024-10-29",
   "2024-10-30",
   "2024-11-01",
   "2024-11-04"
  ],
  "count": 5
 },
 {
  "startDate": "2024-12-22",
  "endDate": "2025-01-16",
  "validDays": [
   "2024-12-23",
   "2024-12-26",
   "2024-12-27",
   "2024-12-30",
   "2024-12-31",
   "2025-01-02",
   "2025-01-03",
   "2025-01-06",
   "2025-01-07",
   "2025-01-08",
   "2025-01-09",
   "2025-01-10",
   "2025-01-13",
   "2025-01-14",
   "2025-01-15",
   "2025-01-16"
  ],
  "count": 16
 }
]

[

{

"startDate": "2024-09-10",

"endDate": "2024-09-23",

"validDays": [

"2024-09-10",

"2024-09-11",

"2024-09-12",

"2024-09-13",

"2024-09-16",

"2024-09-17",

"2024-09-18",

"2024-09-19",

"2024-09-20",

"2024-09-23"

"count": 10

{

"startDate": "2024-10-26",

"endDate": "2024-11-04",

"validDays": [

"2024-10-28",

"2024-10-29",

"2024-10-30",

"2024-11-01",

"2024-11-04"

"count": 5

{

"startDate": "2024-12-22",

"endDate": "2025-01-16",

"validDays": [

"2024-12-23",

"2024-12-26",

"2024-12-27",

"2024-12-30",

"2024-12-31",

"2025-01-02",

"2025-01-03",

"2025-01-06",

"2025-01-07",

"2025-01-08",

"2025-01-09",

"2025-01-10",

"2025-01-13",

"2025-01-14",

"2025-01-15",

"2025-01-16"

"count": 16

}

]

The getWorkdays() function

Parameters

This function takes three arguments:

workperiod: This is the array object containing the start date and end date for each of the sample periods.
weekends: The array of designated weekends as a number. For example, Saturday and Sunday would look like this: [0,6]
holidays: An array of holidays as date strings.

Function Variables and UTC dates

In this section, we’ll prepare our dates for efficient comparison by converting them into milliseconds so that we can extract our valid dates.

Calculating a Whole Day in Milliseconds (Line 16):

- - We start by calculating the duration of a whole day in milliseconds. This will allow us to iterate over each day and check if it is a valid date.

Handling Timezone and Daylight Saving (Lines 22-29):

- To avoid any timezone-related quirks or issues with daylight-saving events, we’ll convert our date periods to Coordinated Universal Time (UTC). We’ll create a small private method at the top of our function to handle this conversion.
- Note: We’ll encounter UTC conversions multiple times in our code, so having a dedicated method simplifies things.

Converting the Array of Holiday Dates to UTC Time (Line 32):

- Finally, we’ll convert our holiday array of dates to UTC time in milliseconds so that we can directly reference them against the currently iterated day.

Map an array of workdays

Next, we need to map our array of found workdays for each sample date range (Line 35). To do this we will use the JavaScirpt map method that takes a function as an argument.

Map Variables

We will need to iterate through each day within our date range checking if the date is not a weekend or a holiday and then record that date. To do this, we will need to set a few variables.

Get start and end days as UTC time in milliseconds (Lines 37-38)

Both the start date and end date will need to be converted to UTC dates using our private getUTC() method.

Set Mutable Variables ( Lines 41-42)

When we look at each date we need to check that day’s day of the week. To determine the starting day of the week of our range of dates we use the JavaScirpt getDay() method. This will update for each new day we check.
Next, we need to set our first day to check as a day.

Store Valid Wordays (Line 44)

Here we store our valid workdays in the validWorkday array.

Iterating over the days in the range

Our main task now is to iterate over each day in the range.

Not a Weekend or a Holiday (Line 49-52)

First, we check if the current day of the week is not included in the weekends array and the current day in UTC format does not exist in the holidayUTC array.
If both of these conditions are met, then the day is a valid workday and we add it to our validWorkay array.

Preparing for the Next Day (Lines 54-55)

Now we need to prepare for the next day check by:
- Updating the day by another day using the dayMilliseconds variable.
- Getting the next day of the week. Here, we need to keep in mind that if the next day of the week is equal to seven then it will go back to the start of the week which will be zero.

Returning it all back

Once we have our valid workday for the selected range, we return that array to generate our mapped array of workdays.

Finally, we return the workdays array back to the calling function.

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

That’s all there is to get a list of valid workdays in a range in JavaScript. I use this function often when providing analysis tools for clients who want to see aggregate workdays over a period of days.

I’d love to hear what you would use this function for.

~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:

Features

Mobile Input will display the number pad

Value retrieval

Automatically moves to the next input

Client-Side Validation

Removing ‘Accepted’ number input characters that are not numbers

Cannot exceed the number range

Returning back a tab will clear the field

Prepends Zeros (0) to Any Number Not At Max Character Length

Quickly add or remove a time input

The Code for the Custom Time Input field

Example 1: Single time field

Example 2: Multiple time fields

Example 3: Build Multiple HTML Custom Time Input fields dynamically with JavaScript

Conclusion

Share this:

Like this:

Requirements

Setup

Install the TypeScript Package for Sublime Text

Check for the TypeScript Package

Add the TypeScript Package

Linux

Windows

Mac

Install the Google Apps Script Type Package

Testing the Google Apps Script text completion in Sublime Text

Navigating Autocomplete

Tooltips – Method argument instructions

Look at Multiple Arguments or tooltips

Rename a Variable, Class or Function

Formatting

Getting *.gs files to display autocomplete

Conclusion

Share this:

Like this:

Share this:

Like this:

The Example

The Video Tutorial

The Code

The runsies() function

The getWorkdays() function

Parameters

Function Variables and UTC dates

Map an array of workdays

Map Variables

Iterating over the days in the range

Returning it all back

Share this:

Like this: