grade

Grade is a small JavaScript library that looks at an image on a web page and automatically generates a matching color gradient for the background behind it. It picks the two most prominent colors from the image and blends them into a smooth gradient that wraps the image in a visually coordinated frame, without any manual color picking required.

The typical use case is a music or movie app, a product page, or any design where you want album art, poster images, or product photos to feel integrated with the surrounding page rather than floating on a plain white or fixed-color background. Instead of choosing a background color yourself, Grade reads the image and figures out what fits.

Setup is straightforward: you wrap each image in a container element, then call the library with a reference to those containers. Grade scans each image using the browser's built-in canvas drawing system, extracts the dominant colors, and applies the resulting gradient as a CSS background on the container. No server-side processing is involved.

The library can be added to a project by downloading the file directly, loading it from a CDN, or installing via npm. There is also an option to receive the gradient data as a JavaScript object rather than having it applied to the page automatically, which lets developers use the extracted colors in their own way.

One practical limitation: because the library reads pixel data from images using the browser's canvas element, it cannot process images hosted on a different domain unless that domain has been configured to permit cross-origin access. The README includes instructions for enabling this on Amazon S3. The library is released under the MIT license.