@n1kk/contrast-color

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

# 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]