The purpose of this package is to provide all necessary functions for working with CSS colors as well as additional useful utilities for real-world use-cases.
Installation
yarn add @adeira/css-colors
Usage
Get color keywords
import { cssColorNames } from '@adeira/css-colors';
cssColorNames.get('rebeccapurple'); // => #663399
The imported cssColorNames
is a Map
of all CSS keywords, so you can use any available Map
methods.
Is it a color?
import { isColor } from '@adeira/css-colors';
isColor('#663399'); // true
isColor('rebeccapurple'); // true
isColor('rgb(255, 255, 128)'); // true
isColor('transparent'); // true
isColor('currentcolor'); // true
isColor('hsl(50, 33%, 25)'); // false (last number should be 25%)
What is the color contrast ratio?
This function takes triplet of colors for foreground and background colors and calculates their contrast ratio (from 1:1 for no contrast up to 25:1 for excellent contrast):
import { calculateContrastRatio } from '@adeira/css-colors';
calculateContrastRatio([130, 242, 75], [119, 46, 242]); // 4.27 (4.27:1)
Is the pair of colors accessible?
Allows you to decide whether a pair of two colors (typically foreground and background) is accessible:
import { isAccessible } from '@adeira/css-colors';
isAccessible([0, 0, 0], [255, 255, 255]); // true (black and white combo)
// optionally, you can specify context of these colors and success criteria for accessibility:
isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AAA'); // false
isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AA'); // true
isAccessible([64, 32, 17], [201, 120, 136], 'LARGE_TEXT', 'AAA'); // true
isAccessible([64, 32, 17], [201, 120, 136], 'GRAPHICAL_OBJECTS'); // true
Note on colors accessibility: it can happen that some backgrounds are never accessible under AAA criteria. For example #FF1A1A
always fails "normal text" test for AAA criteria (no matter whether you choose completely white or completely black font).
What color is the best for this background?
import { chooseHigherContrast } from '@adeira/css-colors';
chooseHigherContrast(
[255, 255, 255], // foreground color 1 ✅
[128, 128, 128], // foreground color 2 ❌
[0, 0, 0], // background
);
The function above returns [255, 255, 255]
because white is better on a black background than grey.
Normalize colors
import { normalizeColor } from '@adeira/css-colors';
normalizeColor('#639'); // #639
normalizeColor('#663399'); // #639
normalizeColor('rebeccapurple'); // #639
HEX to HEX
import { hex3ToHex6, hex6ToHex3 } from '@adeira/css-colors';
hex3ToHex6('#639'); // #663399
hex6ToHex3('#663399'); // #639
Is the color bright or dark? (DEPRECATED)
This function can be used to detect whether the color is bright or dark, so you can decide whether you should use white or black text for the color background (or vice versa):
import { isDark, isBright } from '@adeira/css-colors';
isDark([0, 0, 0]); // true (it's black)
isBright([0, 0, 0]); // false
isDark([144, 238, 144]); // false (lightgreen)
isBright([144, 238, 144]); // true
isDark([255, 255, 255]); // false (it's white)
isBright([255, 255, 255]); // true
Please note that while this function is simple, it takes into account only one color. Consider using calculateContrastRatio
and/or isAccessible
described above where you can specify 2 colors (for example, text and its background).
convertToRGBTriplet
TKTK