A lightweight tool that parses color strings and recommends text contrast based on WCAG Standards
Install constrastrast by running one of the following commands:
npm install --save constrastrast@latest
yarn add constrastrast@latest
pnpm install --save constrastrast@latest
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>
}constrastrast supports the following color string formats:
HEX Notation in either 3 or 6 length format
examples
#ad1232
ad1232
#ada
ada
Standard RGB notation
examples
rgb(100,200, 230)
rgb(5, 30, 40)
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)
Currently contrastrast doesn't support alpha formats and will log an error and return the default value
If an unhandled string is passed, by default contrastrast will log an error and return the default value ("dark")
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
};Happy for any and all contributions. Please note the project uses pnpm and I prefer to have git commits formatted with gitmoji-cli