Contrast Checker

ColorChecker is a JavaScript utility for analyzing and comparing colors in relation to DOM elements. It computes the average color of a DOM element’s subregion (e.g. a child element) and matches it to the closest color from a provided palette based on luminance similarity.

Features

• Computes the average color of the background image within the region of a DOM element.
• Compares the average color to a given list of colors and finds the color with the most contrast.
• Debug mode appends the calculated average color to the DOM and logs the results.
• Lightweight and easy to integrate.

Demo

Check out the demo here

Installation

You can include the script in your project by installing it from npm:

1npm install @roussos/contrast-checker

Usage

Initialization

Create a new instance of ColorChecker and set the parent and child elements.

• If you initialize the instance without the parent option, it will try to find the closest element containing an image.

• You can also initialize it without any options, but in that case, you must call the updateOptions method manually.

1const checker = new ColorChecker({
2    child: '#childElement',
3    parent: document.querySelector('#parentElement')
4})

Compare Colors

Use the compare method to find the closest matching color from an array of colors.

The colors in the array MUST be in hexadecimal form.

1const closestColor = checker.compare(['#ffffff', '#d23d11', '#02004b']);
2console.log('Closest Color:', closestColor);

Update Elements

Use the updateOptions method to change the provided element options.

1checker.updateOptions({
2    child: '#newChildElement',
3    parent: document.querySelector('#newParentElement')
4})

Debug Mode

Enable debug mode to append the calculated average color to the DOM and log the results.

1const closestColor = checker.compare(['#ffffff', '#d23d11', '#02004b'], true);

API

ColorChecker(options)

Creates a new instance of ColorChecker.

Parameters:

Options	Type	Description
child	HTMLElement, String	The child element whose background is analyzed.
parent	HTMLElement, String	The parent element behind the child. Must be an element or an element containing one.

---

compare(color, debug)

Finds the closest matching color from the provided array.

Parameters:

Options	Type	Description
color	String[]	Array of hexadecimal colors to compare.
debug	Boolean	Optional. If true, appends the calculated average color to the DOM. Default is false.

Returns: The color from the array that has the most contrast to the average color of the parent element.

---

compareAsync(color, debug)

Same as compare but it returns a promise with the computed color.

---

updateOptions(options)

Updates the instance's options with new Child and Parent elements.

Parameters:

Options	Type	Description
child	HTMLElement, String	The child element whose background is analyzed.
parent	HTMLElement, String	The parent element behind the child. Must be an element or an element containing one.

Returns: The ColorChecker instance, allowing method chaining.

---

Example

1import ColorChecker from '@roussos/contrast-checker';
2
3const checker = new ColorChecker({
4    child: '#lorem',
5})
6
7document.querySelector('#lorem').style.color = checker.compare([
8    '#ffffff', 
9    '#d23d11', 
10    '#02004b'
11])

License

This project is licensed under the MIT License.