The definitive source of the best
JavaScript libraries, frameworks, and plugins.

  • ×

    Background Check

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

    • 🔾47%Overall
    • 3,266
    • 61.9 days
    • 🕩283
    • 👥3


    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.

    Show All