dye.js Color Library

What is dye.js

dye.js is a small TypeScript library for adapting element colors based on the background they sit on. It was created as an accessibility-oriented experiment: reduce the repetitive work of managing contrast when interface colors change dynamically.

The library can evaluate an element’s own background or a parent background, then adjust text, icon, or black-and-white image treatment so the result remains readable. It is deliberately lightweight, because this kind of behavior should not require a heavy dependency.

Use Case

The core use case is simple: when a background color changes, the foreground needs to stay legible. That can happen in theme builders, color pickers, generated palettes, CMS-driven sections, and interactive design tools.

Instead of writing one-off logic for each component, developers can apply a data attribute and let dye.js handle the color decision. It also supports solid colors and simple gradients with up to three colors.

Features

• Dynamic color adaptation for text, icons, and black-and-white images.
• Contrast-aware behavior designed around WCAG principles.
• Simple integration through data attributes.
• Selector-based targeting for parent elements.
• Solid color and simple gradient detection.
• TypeScript source with a small runtime footprint.

1. ELEMENTS

To apply Dye.js to a regular HTML element, simply add the “dye” attribute. This will work for elements that have their own background color.

<p dye>This element's color changes based on its background color</p>

The above instruction works for elements with a background color, or for images where the parent element has a background color. If the element doesn’t have a background color, specify the parent:

<p dye=".this-is-the-element-with-bg">
  This element's color changes based on the provided element's background color
</p>

2. IMAGES

Currently, Dye.js changes the color of black / white images or icons. Follow the same logic as above, but add the “blackimg” parameter for black source images:

<img src="blackimage.png" dye="#this-is-an-id" blackimg>

By default, Dye.js checks the parent background color for images. To use a different color from a remote relative, provide the element to the dye=”” parameter:

<img src="blackimage.png" dye="#this-is-the-id-element-with-bg-color" blackimg>

3. GRADIENTS

Starting from version 0.4.3, Dye.js supports gradients with up to three colors. Keep in mind that the output might not be 100% accurate for complex gradients, but it works well with simple gradient backgrounds. This feature currently only changes text color and supports RGB, RGBA, and HEX colors.

To use gradients, add the “gradient” attribute to elements with a gradient background.

<p dye="#this-in-the-parent-id-with-gradient-bg" gradient>
  This element's color changes based on the parent gradient background.
</p>

IMPORTANT NOTES

When specifying a selector, identify it as a class or id using the syntax below.

Use . or # to inform Dye.js that the selector is an id or class, respectively.

<img src="blackimage.png" dye="#this-is-an-id" blackimg>

<img src="blackimage.png" dye=".this-is-an-class" blackimg>