homerjam/background-check

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

#BackgroundCheck

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

Examples

• Project Page
• Slider
• Fixed Nav
• CSS Backgrounds
• CSS Backgrounds — Fullscreen
• Cross-Origin Request
• Cross-Origin Request — CSS Backgrounds

Using BackgroundCheck with other plugins

• FlexSlider — Slide
• FlexSlider — Fade

##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;
}

or:

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

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

##How to use

Initialize

// Check all elements with a .target class against all images on a page
BackgroundCheck.init({
  targets: '.target'
});

// Specific images
BackgroundCheck.init({
  targets: '.target',
  images: '.thumbnails'
});

Reprocess

// All targets
BackgroundCheck.refresh();

// Specific target
BackgroundCheck.refresh(target);

Setters and getters

// Get current targets
BackgroundCheck.get('targets');

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

Stop

BackgroundCheck.destroy();

##Attributes

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);
}

BackgroundCheck.init({
  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.