bbc / color-contrast-checker

An accessibility checker tool for validating the color contrast based on WCAG 2.0 and WCAG 2.1 standards.

Color Contast Checker

An accessibility checker tool for validating the color contrast based on WCAG 2.0 and WCAG 2.1 standard.

The formula (L1/L2) for contrast is based on [ISO-9241-3] and [ANSI-HFES-100-1988] standards as described here :

http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef http://www.w3.org/TR/WCAG20/#contrast-ratiodef https://www.w3.org/TR/WCAG21/#contrast-minimum

It also supports shorthand color codes e.g #FFF or #000 etc.

https://www.w3.org/TR/2001/WD-css3-color-20010305#colorunits

Installation:

npm install color-contrast-checker

or using package.json

{
  "name": "my-app",
  ..
  "devDependencies": {
    ..
    "color-contrast-checker": "2.1.0"
  }
}

Then do npm install

Usage:

To check specific WCAG levels

var ccc = new ColorContrastChecker();

var color1 = "#FFFFFF";
var color2 = "#000000;

if (ccc.isLevelAA(color1, color2, 14)) {
    alert("Valid Level AA");
} else {
    alert("Invalid Contrast");
}

To check custom ratios

var ccc = new ColorContrastChecker();

var color1 = "#FFFFFF";
var color2 = "#000000;
var customRatio = 5.7;

// No need for font size, now that we are using a custom ratio.
// This is because we are no longer checking against WCAG requirements.
if (ccc.isLevelCustom(color1, color2, customRatio)) {
    alert("Above given ratio");
} else {
    alert("Invalid Contrast");
}

Advanced Usage:

You can pass pairs and get results:

    var pairs = [
        {
            'colorA': '#000000',
            'colorB': '#000000',  // All should fail
            'fontSize': 14
        },
        {
            'colorA': '#000000',
            'colorB': '#FFFFFF',  //All should pass
            'fontSize': 14
        },
        {
            'colorA': '#000000',
            'colorB': '#848484',  //AAA should fail
            'fontSize': 14
        },
        {
            'colorA': '#000000',
            'colorB': '#848484',  //All should pass (because of font)
            'fontSize': 19
        },
        {
            'colorA': '#000000',
            'colorB': '#757575',  //AA should pass AAA should fail
            'fontSize': 14
        },
        {
            'colorA': '#000000',
            'colorB': '#656565',  //All should fail
            'fontSize': 14
        }
    ];

    var results = ccc.checkPairs(pairs);

The result will look like this:

[
    {
        'WCAG_AA' : false,
        'WCAG_AAA': false
    },
    {
        'WCAG_AA' : true,
        'WCAG_AAA': true
    },
    {
        'WCAG_AA' : true,
        'WCAG_AAA': false
    },
    {
        'WCAG_AA' : true,
        'WCAG_AAA': true
    },
    {
        'WCAG_AA' : true,
        'WCAG_AAA': false
    },
    {
        'WCAG_AA' : false,
        'WCAG_AAA': false
    }
]

Tests

npm test

Contributing

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

color-contrast-checker's Issues

Error: define cannot be used indirect

I'm trying to import this package into React.
None of these works:

import { ColorContrastChecker } from "color-contrast-checker";
import ColorContrastChecker from "color-contrast-checker";

Thank you.

Updating 2.0 Standard to 2.1

Upon reading the 2.1 success criterion here, it looks like nothing has changed since 2.0 in terms of contrast ratio.

Just a heads up in case you'd like to update your readme!

Thanks

Dealing with shorthand color codes

When using color shorthands (e.g. #fff), the tool doesn't recognize the input.

Message: Invalid Color :#fff

include a TS declaration file

It should also consider font weights for determining thresholds for aa and aaa

CSS variable is invalid color

I'm using this code to get CSS variable color and check its contrast:

const titleColor = getComputedStyle(document.documentElement).getPropertyValue('--titleTextColor')

And every time I get this error:
Error: Invalid Color : #000000 at ColorContrastChecker.hexToLuminance

Can't figure out why that happens.

Webpage Url Checker - Feature Request

@nasreenshaik : "Is there a way were we can send the whole webpage url and get the output. writing for each component this way is very difficult"

Is fontSize considered bold in the test?

Wasn't sure what the definition was here since using bold seems to be a determining factor in contrast.

Integration with wcag-validator?

Can this module be integrated with wcag-validator? if yes please guide me how. I want to use it for accessibility testing.
Wcag-validator does not have the contrast module in it so this seems to be the best fit but I have no idea how to build a js project so need guidance.

Why use this tool?

I am curious why someone would choose this tool over all of the other accessibility tools out there. Is there an advantage of doing it via the command line? You can do that with axe & lighthouse too of course.

Cannot find module 'color-contrast-checker'

I am getting "Error: Cannot find module 'color-contrast-checker'" when using the given code. Please advise.

Thanks