Accessibility

apcaContrast

Get the APCA (Accessible Perceptual Contrast Algorithm) contrast value between a background and foreground. APCA is being developed for WCAG 3.0 and provides more nuanced contrast assessment.

apcaContrast(background: string, foreground: string): number

Returns the Lc (Lightness Contrast) value, typically ranging from -108 to +106.

import { apcaContrast } from 'colorizr';

apcaContrast('#000000', '#ffffff'); // 106.04067
apcaContrast('#ffffff', '#000000'); // -107.88473
apcaContrast('#ff0044', '#ffffff'); // -69.23659

Note

APCA is directional — the contrast value differs depending on which color is the background vs foreground. The APCA_VERSION constant (0.0.98G-4g) is also exported.

Playground

-69.23659

The quick brown fox jumps over the lazy dog

✓ Body: 69.2 Lc✓ Large: 69.2 Lc✓ Non-text: 69.2 Lc

contrast

Get the WCAG 2.x contrast ratio between two colors. Returns a value from 1 (no contrast) to 21 (maximum).

contrast(left: string, right: string): number

import { contrast } from 'colorizr';

contrast('#000000', '#ffffff'); // 21
contrast('#ff0044', '#ffffff'); // 3.94
contrast('#1a1a2e', '#ffffff'); // 17.05

Playground

3.94

The quick brown fox jumps over the lazy dog

✗ AA: 3.94:1✓ AA Large: 3.94:1✗ AAA: 3.94:1✗ AAA Large: 3.94:1

readableColor

Get the most readable text color (light or dark) for a given background.

readableColor(backgroundColor: string, methodOrOptions?: ReadableColorMethod | ReadableColorOptions): string

Parameter	Description	Type	Default
darkColor	Dark text color	string	’#000000’
lightColor	Light text color	string	’#ffffff’
method	Algorithm: 'yiq', 'wcag', 'contrast', 'oklab', or 'apca'	string	’yiq’
threshold	Threshold for threshold-based methods (yiq: 0-255, wcag/oklab: 0-1)	number

import { readableColor } from 'colorizr';

readableColor('#ff0044');          // '#ffffff'
readableColor('#ffffff');          // '#000000'
readableColor('#ff0044', 'apca');  // '#ffffff'
readableColor('#ff0044', { method: 'apca', darkColor: '#1a1a2e' }); // '#1a1a2e'

Playground

#ffffff

The quick brown fox jumps over the lazy dog