CSS contrast-color() Function

The CSS contrast-color() function chooses either black or white by comparing both colors with a supplied color. You can use it when a component has a changing background and needs a readable foreground color without maintaining many color pairs.

This function is especially useful for buttons, badges, tags, and theme previews. It became broadly available in modern browsers in 2026, so production pages should still include a tested fallback for older browsers.

How contrast-color() Works

You pass one valid CSS color to the function. The browser compares that color with black and white, then returns the option with the greater contrast. If both choices have equal contrast, the function returns white.

Syntax:

color: contrast-color(<color>);

Create a Button with Automatic Text Color

Store the component color in a custom property. Use the same value for the background and pass it to contrast-color() for the text. You can then change one variable without separately updating the foreground color.

Example:

/* Keep the background color in one reusable variable. */
.button {
  --button-color: #0057b8;
  display: inline-block;
  padding: 12px 20px;
  border-radius: 6px;
  background: var(--button-color);
  color: contrast-color(var(--button-color));
  font: 600 16px Arial, sans-serif;
}

The browser uses white text for this dark-blue button. If you replace the custom property with a light yellow, it chooses black instead. The linked Run Code example lets you change the color and compare the result.

Add a Fallback for Older Browsers

Declare a dependable text color before the modern declaration. Browsers that understand contrast-color() replace the fallback; older browsers retain it.

Example:

.status-badge {
  --badge-color: #6b2fb8;
  background: var(--badge-color);
  color: white; /* Fallback for older browsers */
  color: contrast-color(var(--badge-color));
}

You can also isolate fallback rules with a feature query:

/* Apply this rule only when contrast-color() is unavailable. */
@supports not (color: contrast-color(red)) {
  .status-badge {
    color: white;
  }
}

Use contrast-color() with User-selected Colors

A theme picker can write a color into a custom property while CSS chooses the text color. Keep validation on the application side so the stored value remains a valid CSS color.

Example:

.profile-card {
  --card-color: light-dark(#e8f0ff, #17233d);
  background-color: var(--card-color);
  color: contrast-color(var(--card-color));
  border: 1px solid currentColor;
}

Accessibility Considerations

contrast-color() picks the better of black and white, but that does not guarantee enough contrast for every middle-range background. Small text normally needs a contrast ratio of at least 4.5:1 under WCAG guidance. A medium blue or gray can still produce a weak result even when one choice is mathematically better.

• Prefer distinctly light or dark component backgrounds.
• Test important color combinations with a contrast checker.
• Do not use color alone to communicate an error, warning, or success state.
• Keep focus indicators visible against both the component and page background.

Tip: Treat contrast-color() as a convenient color-pairing tool, not as a complete accessibility audit.

When to Use It

Use the function when one component accepts many known background colors and only needs black or white foreground text. Use manually selected colors when brand requirements demand another foreground color, when translucent layers change the final rendered color, or when a strict contrast target must be guaranteed.

Conclusion

The CSS contrast-color() function reduces duplicated color rules by choosing black or white from one input color. Combine it with custom properties, a deliberate fallback, and real contrast testing to build flexible components that remain clear and readable.