constrastrast

A lightweight tool that parses color strings and recommends text contrast based on WCAG Standards

Installation

Install constrastrast by running one of the following commands:

npm install --save constrastrast

yarn add constrastrast

pnpm install --save constrastrast

deno add contrastrast

How it works

constrastrast takes a given background color as a string in either HEX, HSL, or RGB format, and (by default) returns "dark" or "light" as a recommended text variant for that given background color

For example, you may use it like this:

import { textContrastForBGColor } from "contrastrast";

const MyColorChangingComponent = (backgroundColor: string) => {
    return <div style={{ backgroundColor }} className={textContrastForBGColor(backgroundColor) === "dark" : "text-black" : "text-white"}>
        This text is readable no matter what the background color is!
    </div>
}

Supported Color Formats

constrastrast supports the following color string formats:

HEX

HEX Notation in either 3 or 6 length format

examples

#ad1232

ad1232

#ada

ada

RGB

Standard RGB notation

examples

rgb(100,200, 230)

rgb(5, 30, 40)

HSL

HSL Notation with or without the symbol markers

examples

hsl(217°, 90%, 61%)

hsl(72°, 90%, 61%)

hsl(121deg, 90%, 61%)

hsl(298, 90, 61)

Alpha Formats

Currently contrastrast doesn't support alpha formats and will log an error and return the default value

Unhandled Formats

If an unhandled string is passed, by default contrastrast will log an error and return the default value ("dark")

Options

textContrastForBGColor takes an ContrastrastOptions object as an optional second parameter, it currently has the following configuration options:

type ContrastrastOptions = {
  fallbackOption?: "dark" | "light"; // Defaults to "dark" if not specified
  throwErrorOnUnhandled?: boolean; // Throws an error instead of returning the `fallbackOption`.  Defaults to `false` if not specific
};

Contributing

Happy for any and all contributions. Please note the project uses pnpm and I prefer to have git commits formatted with gitmoji-cli