Contrast Checker

ProNew

Check text and background colors against WCAG 2.2 contrast: the ratio (never rounded up), AA, AAA and non-text results, a live preview, swap, and a button that suggests the closest foreground that passes.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/contrast-checker

Usage

It implements the WCAG 2.2 contrast ratio. APCA, the model proposed for WCAG 3, is not included and gives different results, especially for light text on dark backgrounds.

Exports

Export	Description
`ContrastChecker`	The two fields, preview, results and suggestion.
`contrastRatio(fg, bg)`	WCAG ratio, with transparent foregrounds flattened onto `bg`.
`wcagResults(ratio)`	`{ aaNormal, aaLarge, aaaNormal, aaaLarge, ui }`.
`suggestForeground(fg, bg, target?)`	The nearest passing foreground, or `null`.
`displayRatio`, `relativeLuminance`, `flatten`	Helpers.

Props

Prop	Type	Default	Description
`defaultForeground`, `defaultBackground`	`string`	`#6b7280`, `#ffffff`	Starting colors.
`onChange`	`({ foreground, background, ratio }) => void`	-	After a valid change.
`sampleText`	`string`	pangram	Text in the preview.

Accessibility

The two color fields are labelled inputs (see Color Field); the swap button has a name that says what it swaps.
The results are a role="status" region, so a change in the ratio is announced politely. Pass and Fail are words with an icon, not only green and red.
The ratio is cut, not rounded: 4.499 shows as 4.49 and fails, so the tool never reports a pass that an audit would reject.
The preview uses the colors you typed; it is for judging, not a replacement for the numbers.

Testing

The component ships with a Testing Library test (contrast-checker.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/contrast-checker

Usage

It implements the WCAG 2.2 contrast ratio. APCA, the model proposed for WCAG 3, is not included and gives different results, especially for light text on dark backgrounds.

Exports

Export	Description
`ContrastChecker`	The two fields, preview, results and suggestion.
`contrastRatio(fg, bg)`	WCAG ratio, with transparent foregrounds flattened onto `bg`.
`wcagResults(ratio)`	`{ aaNormal, aaLarge, aaaNormal, aaaLarge, ui }`.
`suggestForeground(fg, bg, target?)`	The nearest passing foreground, or `null`.
`displayRatio`, `relativeLuminance`, `flatten`	Helpers.

Props

Prop	Type	Default	Description
`defaultForeground`, `defaultBackground`	`string`	`#6b7280`, `#ffffff`	Starting colors.
`onChange`	`({ foreground, background, ratio }) => void`	-	After a valid change.
`sampleText`	`string`	pangram	Text in the preview.

Accessibility

The two color fields are labelled inputs (see Color Field); the swap button has a name that says what it swaps.
The results are a role="status" region, so a change in the ratio is announced politely. Pass and Fail are words with an icon, not only green and red.
The ratio is cut, not rounded: 4.499 shows as 4.49 and fails, so the tool never reports a pass that an audit would reject.
The preview uses the colors you typed; it is for judging, not a replacement for the numbers.

Testing

The component ships with a Testing Library test (contrast-checker.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.