Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Automatically switch to a darker or a lighter version of an element depending on the brightness of images behind it.


Using BackgroundCheck with other plugins

##How it works

If an element overlaps any of the images, either .background--dark or .background--light is added to it. BackgroundCheck does not change an element's style — you must do so using CSS.

For example, if <p> has the following default style:

p {
  color: white;

you can then add the following:

p.background--light {
  color: black;

Classes are only added if the element overlaps an image. An element is considered to overlap an image if at least 50% (configurable) of it's area is covering that image.

###Complex backgrounds

The light and dark classes work well with simple backgrounds, but you might require an additional level of control for elaborate backgrounds. BackgroundCheck adds .background--complex to an element if its background exceeds a certain level of complexity.

This class can be used as an intermediate state:

p.background--light {
  color: black;

p.background--dark {
  color: white;

p.background--complex {
  color: gray;


p.background--dark.background--complex {
  color: #ccc;

p.background--light.background--complex {
  color: #aaa;

##How to use


// Check all elements with a .target class against all images on a page
  targets: '.target'

// Specific images
  targets: '.target',
  images: '.thumbnails'


// All targets

// Specific target

Setters and getters

// Get current targets

// Change targets
BackgroundCheck.set('targets', '.header');




Used with .init(), .set() or .get()

  • targets: Elements to be processed. Type: String, Element or Nodelist. Required.
  • images: Images to be used. Type: String, Element or NodeList. Default: All images on page.
  • changeParent: Determines if classes are added to a target or to its parent. Default: false.
  • threshold: Midpoint between dark and light. Default: 50 (%).
  • minComplexity: Minimum image complexity required before the complex class is added to a target. Default: 30 (%).
  • minOverlap: Minimum overlap required between an element and any of the images for that element to be processed. Default: 50 (%).
  • classes: Classes added to targets. Default: { dark: 'background--dark', light: 'background--light', complex: 'background--complex' }
  • windowEvents: Reprocess on window resize and scroll. Default: true.
  • maxDuration: Maximum processing time allowed. Killed if it takes longer. Default: 500 (ms).
  • mask: Used internally when checking if an element overlaps any of the images. Default: { r: 0, g: 255, b: 0 }
  • debug: Enable or disable logs. Default: false.

##CSS Backgrounds

BackgroundCheck can also be used on an element that has a background-image. For example:

.thumbnail {
  background-image: url(image.jpg);
  targets: '.target',
  images: '.thumbnail'

Background Position and Size

Tested with the following units:

  • background-size: cover, contain, auto, inherit, cm, em, px and %
  • background-position: top, left, center, right, bottom, inherit, cm, em, px and %

Current Limitations

  • background-repeat is not supported and is forced to no-repeat
  • background-origin is forced to padding-box
  • Multiple backgrounds are not supported
  • Four-value syntax can be used if the browser supports it

##Browser Support

Tested on IE 9-11, iOS 6/7 and the latest versions of Chrome, Firefox and Safari.