contrast-color()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The contrast-color() CSS function takes a color value and returns a guaranteed contrasting color.

contrast-color() makes it easy, for example, to specify a text color and automatically generate a contrasting background color, or vice versa. It avoids the need to maintain background-text color pairs.

Syntax

css

contrast-color(red)
contrast-color(var(--backgroundColor))

Parameters

color: Any valid <color> value.

Return value

A <named-color> of either white or black.

Description

The contrast-color() function returns a value of white or black, depending on which value has the greatest contrast with the input color. If both white and black have the same contrast with the input color, white is returned.

Warning: There is no guarantee that the values returned using the contrast-color() function will produce an accessible result. Mid-tone background colors generally don't provide enough contrast. It is recommended therefore to use light or dark colors with the contrast-color() function.

Examples

Contrasting text for a button

In the following example, the browser automatically applies a contrasting color to the submit <button> text when you change its background color.

<label>
  Select background color of the button:
  <input type="color" id="colorPicker" value="#660066" />
</label>
<br />
<button>Submit</button>

css

:root {
  --button-color: lightblue;
}

button {
  background-color: var(--button-color);

  /* Set contrasting text color automatically */
  color: contrast-color(var(--button-color));
}

body {
  padding: 1rem;
}

button {
  margin: 3rem;
  padding: 1rem;
  width: 150px;
  font-size: 2rem;
  border-radius: 1rem;
}

@supports not (color: contrast-color(red)) {
  body::before {
    content: "Your browser doesn't support the contrast-color() function.";
    background-color: wheat;
    display: block;
    width: 100%;
    text-align: center;
  }

  body > * {
    display: none;
  }
}

const colorPicker = document.getElementById("colorPicker");
const root = document.documentElement;

function updateColor(color) {
  root.style.setProperty("--button-color", colorPicker.value);
}

colorPicker.addEventListener("change", updateColor);
updateColor();

Light and dark mode usage

In the following example, the prefers-color-scheme media query is used to set a background color based on operating system or browser color scheme settings. The contrast-color() function is used to set the text color automatically.

Try changing the browser or OS dark mode setting to see the effect.

<pre>
    Q: How does CSS transform light into energy?
  Ans: Using <a href="/en-US/docs/Web/CSS/font-synthesis">font-synthesis</a>.
</pre>

css

:root {
  --background-color: navy;
}

@media (prefers-color-scheme: light) {
  :root {
    --background-color: wheat;
  }
}

body,
a {
  background-color: var(--background-color);
  color: contrast-color(var(--background-color));
}

body {
  padding: 2rem;
  font-size: 1.2rem;
}

pre {
  margin-top: 3rem;
}

@supports not (color: contrast-color(red)) {
  body::before {
    content: "Your browser doesn't support the contrast-color() function.";
    background-color: wheat;
    display: block;
    width: 100%;
    text-align: center;
  }

  body {
    background-color: white;
  }

  body > * {
    display: none;
  }
}

Specifications

Specification
CSS Color Module Level 5 # contrast-color

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on ⁨Jul 14, 2025⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content