What Is the CSS contrast-color() Function?

The CSS contrast-color() function is a modern tool designed to help developers meet Web Content Accessibility Guidelines (WCAG) contrast requirements with minimal effort. It accepts a <color> value—either a direct color or a CSS custom property—and returns either black (#000000) or white (#ffffff), whichever offers the highest contrast against the given background.

Simplify Accessible Color Contrast with CSS contrast-color()

In essence, contrast-color() automates the process of choosing a text color that remains readable on any background, making it particularly useful for theming, dynamic color schemes, or design systems where background colors change.

Syntax and Parameters

The function follows a straightforward syntax:

contrast-color( <color> )

It takes a single mandatory argument: a <color> value. This can be a named color, a hex code, an RGB/A value, or even a CSS variable. Here are a few valid examples:

contrast-color(#34cdf2) – passes a hex color directly
contrast-color(green) – uses a named color
contrast-color(var(--my-background)) – references a custom property

The function resolves to black or white. If both colors have identical contrast ratios against the input background, the function defaults to white.

Basic Usage

The most common use case is to automatically set text color based on a dynamically defined background. For instance:

.card {
  --swatch: #2d5a27;
  background-color: var(--swatch);
  color: contrast-color(var(--swatch));
}

In this example, the text color will be white (since #2d5a27 is a dark green), ensuring readability without hard-coding color pairs.

Practical Example: Theming Without Redundancy

Before contrast-color(), defining multiple themes required pairing each background with a specific text color:

:root {
  --primary-text: #f1f8e9;
  --primary-bg: #2d5a27;
  --secondary-text: #311b92;
  --secondary-bg: #d1c4e9;
}
.primary {
  color: var(--primary-text);
  background: var(--primary-bg);
}
.secondary {
  color: var(--secondary-text);
  background: var(--secondary-bg);
}

With contrast-color(), you can reduce this to just background variables and let the function handle the text:

:root {
  --primary: #2d5a27;
  --secondary: #d1c4e9;
}
.primary {
  color: contrast-color(var(--primary));
  background: var(--primary);
}
.secondary {
  color: contrast-color(var(--secondary));
  background: var(--secondary);
}

This approach scales effortlessly: adding a new theme only requires one new variable.

When Should You Use contrast-color()?

Because the function only returns black or white, it works best in simple designs where a monochrome text palette is acceptable. Common scenarios include:

Cards or banners with user‑defined background colors
Dynamic theming (e.g., dark/light mode toggles)
Design systems where background colors vary but text must remain either black or white

However, for rich color palettes (e.g., using accent colors for text), contrast-color() may be too restrictive. In those cases, it is better to manually define contrasting text colors.

Current Limitations and Considerations

As of this writing, the contrast-color() function is still experimental and part of the CSS Color Module Level 5 specification. Browser support is limited, so production use may require fallbacks or progressive enhancement.

Other limitations include:

Only returns black or white—no possibility for gray or other colors
Does not account for contrast ratios beyond the simple black/white comparison; WCAG success criteria (AA or AAA) may need manual verification for complex backgrounds
May produce unexpected results with transparent or semi‑transparent colors

Despite these shortcomings, contrast-color() is a valuable addition to the CSS toolbox for quickly ensuring baseline contrast, especially when paired with CSS custom properties.

Future of the Function

The CSS Working Group continues to refine the Color Module. Future versions might allow specifying a list of candidate colors, not just black and white, giving developers more flexibility. For now, contrast-color() stands as a practical, if limited, solution for accessible color contrast.

To see the function in action, try the interactive demo in the CodePen example (embedded above). Change the background color and watch the text automatically adapt to maintain readability.

Simplify Accessible Color Contrast with CSS contrast-color()