Contrast Color
A set of methods for working with contrasting colors.
Use cases:
- Get contrasting text color for a given background
- Pick color from the list that has most contrast with a target color
- Get color relative luminance
- Get contrast difference between two colors
- Get contrast ratio between two colors
- Check if two colors have sufficient contrast difference
TypeScript Docs: https://n1kk.github.io/contrast-color/
Demo page: https://n1kk.github.io/contrast-color/demo.html
Usage
Install:
# npm
npm i @n1kk/contrast-color
# yarn
yarn add @n1kk/contrast-color
# pnpm
pnpm i @n1kk/contrast-color
API
contrastingTextColor(backgroundColor, options?) => string
# Get a contrasting text color for a gien background
-
backgroundColor
: supported color value -
options
: optional object that allows you to configure:-
light
color: string -
dark
color: string - luminosity
threshold
: number (0-1)
-
-
returns:
string
of a color which has most contrast with the given background
const textColor1 = contrastingTextColor("#fff"); // "#000000"
const options = { dark: "#222", light: "#eee", threshold: 0.4 };
const textColor2 = contrastingTextColor("#fff", options); // "#222"
ColorValue
- A supported color value:
- int:
0 - 16777215
, - rgb array of int (0-255):
[255, 0, 0]
, - hex color in web or full format:
#RGB
|#RRGGBB
|#RRGGBBAA
- int:
colorsContrast(color1, color2) => number
# Calculates contrast difference of two colors.
-
color1
,color2
: supported color value -
returns:
number
0-1- 0: no difference
- 1: max contrast, black and white
const bnw = colorsContrast("#000", "#FFF"); // 1
const sameColor = colorsContrast("#000", "#000"); // 0
colorsContrastRatio(color1, color2) => number
# Calculates color contrast ratio based on W3C spec
-
color1
,color2
: supported color value -
returns:
number
between 1 (1:1 ratio) and 0.476... (1:21 ratio),- 1:1 : no contrast, same color
- 1:21 : max contrast, black and white
const bnw = colorsContrastRatio("#000", "#FFF"); // 1/21 (0.047..)
const sameColor = colorsContrastRatio("#000", "#000"); // 1
colorsHaveSufficientContrast(color1, color2) => number
# Check if colors have suffiecient contrast ratio (7:1) as defined by W3C spec
-
color1
,color2
: supported color value -
returns:
boolean
colorsHaveSufficientContrast("#000", "#FFF"); // true
colorsHaveSufficientContrast("#000", "#000"); // false
pickMostContrast(colorList, target) => color
# Pick a color from the list that has the most contrast with the target.
-
color
: an array of supported color values - returns: value from the list
pickMostContrast(["#fff", "#f00", "#00f", "#000"], "#000"); // "#fff"
pickMostContrast(["#fff", "#f00", "#00f", "#000"], "#fff"); // "#000"
colorLuminance(color) => number
# Calculates relative color luminance as per W3C spec
-
color
: supported color value -
returns:
number
0-1
colorLuminance("#fff"); // 1
colorLuminance("#000"); // 0
colorLuminance("#F00"); // 0.21...
Utils
hexToRGB(hex) => [r, g, b]
# Convert a hex color to rgb array.
-
hex
: hex color value#RGB
|#RRGGBB
|#RRGGBBAA
- returns: rgb array
hexToRGB("#fff"); // [255, 255, 255]
decToRGB(dec) => [r, g, b]
# Convert a dec color to rgb array.
-
dec
: integer from 0 to 16777215 - returns: rgb array
decToRGB(16777215); // [255, 255, 255]
toRGB(color) => [r, g, b]
# Convert a color values to rgb array. Throws on invalid input.
-
color
: color values - returns: rgb array
toRGB("#fff"); // [255, 255, 255]
toRGB(16777215); // [255, 255, 255]