readable-color v1.1.0

readable-color

Automatically sets the most readable foreground color of an element depending on its background color. More or less.
readable-color can be summarized in: Is background bright ? Write in black. Is background dark ? Write in white.

Why ?

Sometimes the background color value of an element is not known in advance.
Sometimes the background color is coming from an API call or is chosen by the User.
In these situations finding a good foreground color to keep text readable might be complicated.
This library helps whenever you want readable text but you are not sure of the final background color.

Features

• Written in TypeScript
• No dependencies
• Plug'n'play using unpkg
• Very small surface
• Reasonable code coverage

Alternatives

• You can use CSS 3 mix-blend-mode
• You can leverage HSL with color correction

These alternative approaches are better than readable-color, but might be more complicated to implement and reuse.

Limitations

• Understands only colors specified as: named colors, hexdecimal colors, rgb() and rgba()
• Any unknown color value is treated as the color 'white'
• Cannot choose to use something other than 'black' or 'white' as foreground color
• The library must be activated programmatically every time, especially when elements change their background color
• No support for animations
• Might not work in every browser, especially with older browsers like Internet Explorer 11

Getting started

Using NPM

Install the package readable-color, import apply-most-readable-color and call applyMostReadableColor().

When called without arguments it will apply colors to any element decorated with data-apply-most-readable-color.
You can choose to pass applyMostReadableColor() an array of HTMLElements or a NodeList<HTMLElements.

This example colors all div on the page:

import { applyMostReadableColor } from 'readable-color';

...

const elementsToColor = document.querySelectorAll('div');

applyMostReadableColor(elementsToColor);

Using unpkg.com:

Add to your HTML file the following:

<script type="text/javascript" src="https://unpkg.com/readable-color@latest/dist/umd/readable-color.js">

Then, from any other script loaded after, simply call readableColor.applyMostReadableColor() .

How does it work ?

This library calculates the perceived brightness of an element's background color. Depending on the perceived brightness value it will choose to set 'black' or 'white' as foreground color.
This simplistic alghoritm is sufficient to set a foreground color with enough contrast to make any text readable for most users.

The library will parse the element's background color from CSSStyleDeclaration.backgroundColor returned from window.getComputedStyle().
CSS color are parsed using custom 'parser' that understands a subset of the CSS Color Module - Level 4 W3C specification.
No external libraries where used to parse colors to avoid any additional dependencies.