Calculate contrasting font colors for Sheets.

If you are playing around with Sheet colors with Apps Script, you sometimes find yourself with font colors that don’t go well with the background colors you’ve chosen. However, we can use Yiq values to decide whether the luminance of the background color would be best with a light or a dark foreground font color. Here’s a small Apps Script library to figure it out for you.

How to use

We’ll go through the details in this post later, but to get straight to it, you can use it like this after including the bmYiq library.

(Library key: 1gUNJ_axo9Q2tiBkZ5QFfLz03O1SMLR11Z-aZJoMzwImGWwSCwgH0SSW8)

const {Yiq} = bmYiq.Exports

Get contrasting font colors for all the sheets in a range

Here’s how to examine all the background colors in a given range, pick a light or dark font color as appropriate, and apply them.

  Yiq.setFontContrasts ({ range })

Here are some examples of doing selected ranges. Use whichever your favorite method is for creating ranges.

Set font colors for a whole sheet

Yiq.setFontContrasts ({range: sheet.getDataRange()})

Contrasting font colors for a header

const dataRange = sheet.getDataRange()
const range = dataRange.offset(0,0,1,dataRange.getNumColumns())
Yiq.setFontContrasts ({range})

For a specific column

const dataRange = sheet.getDataRange()
const columnOffset = dataRange.getNumColumns() -1
const range = dataRange.offset(0,columnOffset,dataRange.getNumRows(),1)
Yiq.setFontContrasts ({range})

More methods

The library provides a few more methods you might find useful.

Yiq.getContrasts ({backgrounds [, light, dark]})

Given an array of arrays of background colors in hex format ‘#xxxxxx’ , return the same size of array of contrasting foreground colors. See below if you want to do it yourself rather than use Yiq.setFontContrasts.

const range = sheet.getDataRange()
const backgrounds = range.getBackgrounds()
const fontColors = Yiq.getContrasts ({backgrounds})
range.setFontColors(fontColors)
    

Yiq.getContrast({color [, light, dark]})

Return a single contrasting color for a given color.

const fontColor = Yiq.getContrast({color: '#ffaa27'})

If you know there’s only 1 color, you can optimize setting colors by using the setFontColor (as opposed to setFontColors), because that’ll make a shorter call to the spreadsheet api.

const range = sheet.getDataRange()
const fontColor = Yiq.getContrast ({color: '#ffaabb'})
range.setFontColor(fontColor)

Yiq.setFontContrasts() does this automatically. It’ll calculate the fontColors for the range’s background colors, and if they are all the same it’ll optimize the call rather than sending a large array of individual cell colors if it can get away with it.

Light and dark settings

By default, Yiq uses #212121 for dark, and #ffffff for light. If you want to change that, each of the methods above take a couple of extra arguments to allow you to change those if you want.

  const yellow = '#FFF9C4'
  const indigo = '#303F9F'
  const range = sheet.getDataRange()
  Yiq.setFontContrasts({ range, light: yellow, dark: indigo })

Basing the background color on the font color

All the examples so far are for the most likely use case, ie basing the font color on the cell background, but if you want to do the reverse (find contrasting background colors for given font colors), you can do this.

Yiq.setBackgroundContrasts({ range})

Example

Here’s an screenshot of a collection of contrasting font colors chosen for some random background colors.

Yiq with Fiddler

Many of you use my Fiddler library Fiddler – A functional approach to fiddling with sheet data to deal with spreadsheet manipulation, and you can use Yiq with that too.

Contrast font color fiddler header format

  new bmFiddler.Fiddler(sheet)
    .setHeaderFormat({
      backgrounds: '#D32F2F',
      fontColors: Yiq.getContrast({ color: '#D32F2F' })
    })
    .dumpFormats()

Set contrast for entire sheet with fiddler

 Yiq.setFontContrasts({range: new bmFiddler.Fiddler(sheet2).getRange()})

Set a header and particular column contrasts with fiddler

  new bmFiddler.Fiddler(sheet8)
    .setHeaderFormat({
      backgrounds: '#D32F2F',
      fontColors: Yiq.getContrast({ color: '#D32F2F' })
    })
    .setColumnFormat({
      backgrounds: '#03A9F4',
      fontColors: Yiq.getContrast({ color: '#03A9F4' })
    }, ['foo', 'bar'])
    .dumpFormats()

YIQ tldr

Read all about the background behind the YIQ calculation here. In summary, an rgb color can be converted into a YIQ value like this.

Heres’s what these values mean (source)

Library code extract

For our purposes, we’re only interested in the Y of Yiq – that’s the luma of the color.

The code for this is in the bmYiq library and looks like this. You’ll find a link to the full code for the library at the end of this article.

  /**
   * turn a number into a #ffffff rgv hex color
   * @param {number} num turn a number into a #ffffff rgv hex color
   * @return {string}
   */
  numToColor(num) {
    return '#'   ('000000'   (num & 0xFFFFFF).toString(16)).slice(-6)
  },

  // default colors if you want a dark font color
  get defaultDark() {
    return '#212121'
  },
  // default colors if you want a light font color
  get defaultLight() {
    return '#ffffff'
  },

  // threshold for light vs dark for luma value 
  // 150 appears to be the accepted value
  get threshold() {
    return 150
  },

  getYiq(color) {
    const { r, g, b } = this.getRgb(color)
    const y = (r * 0.299)   (g * 0.587)   (b * 0.114)
    const i = (r * 0.596)   (g * -0.274)   (b * -0.322)
    const q = (r * 0.211)   (g * -0.523)   (b * 0.312)
    return {
      y,
      i,
      q
    }
  },

  /**
   * get the rgb object
   * @param {string} color the color
   * @param {string} p.color color to get the contrast of
   * @param {string} [p.color=#ffffff] light font color
   * @param {string} [p.color=#212121] dark font color
   * @return {object} {r,g,b}
   */
  getRgb(color) {
    return {
      r: parseInt(color.substring(1, 3), 16),
      g: parseInt(color.substring(3, 5), 16),
      b: parseInt(color.substring(5, 7), 16)
    }
  },

  /**
   * get the contrasting font color given a background
   * @param {object} p oarams
   * @param {string} p.color color to get the contrast of
   * @param {string} [p.color=#ffffff] light font color
   * @param {string} [p.color=#212121] dark font color
   * @return {string[][]}
   */
  getContrast({ color, light = this.defaultLight, dark = this.defaultDark }) {
    if (!this.isString(color) || !color.match(/^#[0-9a-f]{6}/i)) throw 'please provide color as a hex string #rrggbb'
    const { y } = this.getYiq(color)
    return y > this.threshold ? dark : light
  },

Links

bmYiq library

Library key: 1gUNJ_axo9Q2tiBkZ5QFfLz03O1SMLR11Z-aZJoMzwImGWwSCwgH0SSW8

github: https://github.com/brucemcpherson/bmYiq

bmFiddler library

Library key: 13EWG4-lPrEf34itxQhAQ7b9JEbmCBfO8uE4Mhr99CHi3Pw65oxXtq-rU

github: https://github.com/brucemcpherson/bmFiddler

All the tests referenced in this article

IDE: https://script.google.com/u/0/home/projects/1nZSlfKFyWCjz8ILY5TSzyZQyYBdnTCQRUmXkpnNRdVXuC5qcPSDXP0b4/edit

github: https://github.com/brucemcpherson/testBmYiq

Related