diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 13908676175d708..79d0f9e4a5712ed 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -12321,8 +12321,8 @@ /en-US/docs/Web/CSS/clamp() /en-US/docs/Web/CSS/clamp /en-US/docs/Web/CSS/color-adjust /en-US/docs/Web/CSS/print-color-adjust /en-US/docs/Web/CSS/color_value/color() /en-US/docs/Web/CSS/color_value/color -/en-US/docs/Web/CSS/color_value/color-contrast /en-US/docs/Web/CSS/color_value -/en-US/docs/Web/CSS/color_value/color-contrast() /en-US/docs/Web/CSS/color_value +/en-US/docs/Web/CSS/color_value/color-contrast /en-US/docs/Web/CSS/color_value/contrast-color +/en-US/docs/Web/CSS/color_value/color-contrast() /en-US/docs/Web/CSS/color_value/contrast-color /en-US/docs/Web/CSS/color_value/color-mix() /en-US/docs/Web/CSS/color_value/color-mix /en-US/docs/Web/CSS/color_value/color_keywords /en-US/docs/Web/CSS/named-color /en-US/docs/Web/CSS/color_value/device-cmyk() /en-US/docs/Web/CSS/color_value/device-cmyk diff --git a/files/en-us/web/css/color_value/contrast-color/index.md b/files/en-us/web/css/color_value/contrast-color/index.md new file mode 100644 index 000000000000000..ae93ba788167587 --- /dev/null +++ b/files/en-us/web/css/color_value/contrast-color/index.md @@ -0,0 +1,187 @@ +--- +title: contrast-color() +slug: Web/CSS/color_value/contrast-color +page-type: css-function +status: + - experimental +browser-compat: css.types.color.contrast-color +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`contrast-color()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) takes a {{cssxref("color_value","color")}} value and returns a [guaranteed](https://www.w3.org/TR/WCAG21/#contrast-minimum) 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 {{cssxref("<color>")}} value. + +### Return value + +A {{cssxref("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 {{htmlelement("button")}} text when you change its background color. + +```html hidden + +
+ +``` + +```css +:root { + --button-color: lightblue; +} + +button { + background-color: var(--button-color); + + /* Set contrasting text color automatically */ + color: contrast-color(var(--button-color)); +} +``` + +```css hidden +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; + } +} +``` + +```js hidden +const colorPicker = document.getElementById("colorPicker"); +const root = document.documentElement; + +function updateColor(color) { + root.style.setProperty("--button-color", colorPicker.value); +} + +colorPicker.addEventListener("change", updateColor); +updateColor(); +``` + +{{EmbedLiveSample("Contrasting text for a button", "", 250)}} + +### Light and dark mode usage + +In the following example, the [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) 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. + +```html hidden +
+    Q: How does CSS transform light into energy?
+  Ans: Using font-synthesis.
+
+``` + +```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)); +} +``` + +```css hidden +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; + } +} +``` + +{{EmbedLiveSample("Light and dark mode usage", "", 250)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`contrast()`](/en-US/docs/Web/CSS/filter-function/contrast) +- [CSS colors](/en-US/docs/Web/CSS/CSS_colors) module +- [CSS custom properties](/en-US/docs/Web/CSS/--*) and {{cssxref("var")}} +- [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast) and [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) {{cssxref("@media")}} features +- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) +- [How to have the browser pick a contrasting color in CSS](https://webkit.org/blog/16929/contrast-color/) on webkit.org (2025) +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) on webaim.org (2025) diff --git a/files/en-us/web/css/color_value/index.md b/files/en-us/web/css/color_value/index.md index ab5314703e16281..6ea706461811e8e 100644 --- a/files/en-us/web/css/color_value/index.md +++ b/files/en-us/web/css/color_value/index.md @@ -76,6 +76,7 @@ A `` value can be specified using one of the methods listed below: - Other color spaces: {{CSSXref("color_value/color", "color()")}}. - By using [relative color](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) syntax to output a new color based on an existing color. Any of the above color functions can take an **origin color** preceded by the `from` keyword and followed by definitions of the channel values for the new **output color**. - By mixing two colors: {{CSSXref("color_value/color-mix", "color-mix()")}}. +- By specifying a color that you want a contrasting color returned for: {{CSSXref("color_value/contrast-color", "contrast-color()")}}. - By specifying two colors, using the first for light color-schemes and the second for dark color-schemes: {{CSSXref("color_value/light-dark", "light-dark()")}}. ### `currentcolor` keyword diff --git a/files/en-us/web/css/css_colors/index.md b/files/en-us/web/css/css_colors/index.md index 91ddced7bdd9e7c..4a88a659d546f6b 100644 --- a/files/en-us/web/css/css_colors/index.md +++ b/files/en-us/web/css/css_colors/index.md @@ -47,6 +47,7 @@ To see the code for this color syntax converter, [view the source on GitHub](htt - [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch) - [`color()`](/en-US/docs/Web/CSS/color_value/color) - [`color-mix()`](/en-US/docs/Web/CSS/color_value/color-mix) +- [`contrast-color()`](/en-US/docs/Web/CSS/color_value/contrast-color) - {{CSSXref("color_value/light-dark", "light-dark()")}} > [!NOTE] diff --git a/files/en-us/web/css/css_values_and_units/css_value_functions/index.md b/files/en-us/web/css/css_values_and_units/css_value_functions/index.md index 49c08b219181a52..d54ce15a22f8a1f 100644 --- a/files/en-us/web/css/css_values_and_units/css_value_functions/index.md +++ b/files/en-us/web/css/css_values_and_units/css_value_functions/index.md @@ -202,6 +202,8 @@ The {{CSSxRef("color_value","<color>")}} CSS [data type](/en-US/docs/Web/C - : Specifies a particular, specified colorspace rather than the implicit sRGB colorspace. - {{CSSxRef("color_value/color-mix", "color-mix()")}} - : Mixes two color values in a given colorspace by a given amount. +- {{CSSxRef("color_value/contrast-color", "contrast-color()")}} + - : Returns a color with maximum color contrast for a given color. - {{CSSxRef("color_value/device-cmyk", "device-cmyk()")}} - : Defines CMYK colors in a device-dependent way. - {{CSSXref("color_value/light-dark", "light-dark()")}}