#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
##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 tono-repeat
background-origin
is forced topadding-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.