Contrast-color() - Function CSS

contrast-color()

Summary of characteristics of the contrast-color() function

Quick description
Determine a foreground color based on the background color to maximize contrast.
Status
Compatibility issues ⚠
Percentages
Not applicable.
Initial value
auto
Animation type
Discrète: during an animation, the contrast-color() property passes from one value to another without transition.
Canonical order
Single: single value (no order).
W3C Module
CSS Color Module
References (W3C)
Document status: WD (Working Draft)

Syntax diagram of contrast-color().

contrast-color() - Syntax DiagramSyntax diagram of the contrast-color() CSS function. color colorcontrast-color()contrast-color()
Syntax diagram of the contrast-color() function.
Click on the terms of the diagram for more precision.

On the diagram, the terms in bold are the predefined terms in CSS, the others are described below:

  • color is a color, expressed in any format recognized by CSS (see Colors).

Description of the contrast-color() function.

When colors are created dynamically, it can sometimes be tricky to find a text color that contrasts enough with the background. The function contrast-color() determines a color with sufficient contrast to be displayed over a background of the specified color. The returned color can be either white or black.

Of course, if the background is not solid (an image, for example), the contrast-color() function cannot be effective.

⚠ This feature is still poorly supported by browsers. If you use a compatible browser (like Firefox  ), the text below will be displayed in white. Otherwise, you won't see the text at all.

Texte

The contrast-color() value can be used with the following properties:

Primarily used with the color property, the contrast-color() function can also be suitable for any properties that expect a color.

    Syntaxes of the contrast-color() function.

    • <property>: color-contrast(#ff8045); color

      coloris a color expressed in any syntax recognized by CSS (see Colors). The function returns white or black depending on which color has the best contrast characteristics with the color.

    Animation with the contrast-color() function.

    The animation is done based on the background color, between white and black. The text color, however, is set to contrast-color(). On compatible browsers, you should always be able to read the text, in black on a white background or white on a black background.

    L'

    Automatic colored text

    Simulator.

    The simulator allows you to change the background color of the block below. The text color, however, is set by contrast-color().

    Note: the simulator sets a variable (custom property) named --demo1, which is then used to determine the background color and is passed as a parameter to the function contrast-color() to determine the foreground color.

    --demo1 :
    Text

    Browsers compatibility with contrast-color() function.

    The function contrast-color() is still very poorly supported by browsers (2025). It is still too early to use it.

    Column 1
    Browser support for the contrast-color() function, which determines the color (between white and black) that has the highest contrast with a given color.
    1
    cntrast-color()
    function
    Estimated overall support.
    3%

    Browsers on computers :

    Mobile browsers :

    Outdated or marginal browsers :

    Internet Explorer

    UC Browser pour Androïd

    Opéra Mobile

    QQ Browser

    Baidu Browser

    Safari

    Samsung Internet

    Safari sur IOS

    Androïd Brower

    Chrome

    Chrome pour Androïd

    Edge

    Firefox

    Firefox pour Androïd

    KaiOS Browser

    Opéra

    Opéra mini

    See Caniuse.com for more compatibility information.
    Caniuse

    Historic of the contrast-color() function.

    • CSS Color Module Level 5

      Introduction of the contrast-color() function to determine a foreground color based on the background color.
      WD
      March 03, 2020
      Working Draft.
      CR
      PR
      REC

    See also, regarding colors.

    Below is the list of properties, functions, and other terms related to color management in CSS.

    Properties:

    color
    Sets the foreground color and assigns a value to currentcolor.
    opacity
    Sets the opacity (inverse of transparency) of an element and its descendants.

    Functions:

    color()
    Defines a color in any color space (sRGB, sRGB-linear, profoto, etc).
    color-mix()
    Langue française
    Mix two colors in a given color space.
    ⚠
    device-cmyk()
    Langue française
    Define a color based on a device, specifying cyan, magenta, yellow, and black values.
    hsl()
    Determines a color from the Hue, Saturation and Brightness settings, an alternative closer to our way of thinking.
    hsla()
    Langue française
    Determines a color and its transparency from the Hue, Saturation, Brightness and Alpha parameters.
    hwb()
    Langue française
    Defines a color based on its hue and a dose of black and white.
    lab()
    Defines a color in the L*a*b* system.
    lch()
    Defines a color in the L*C*H* system.
    oklab()
    Defines a color in the L*a*b* system with a perceptual correction.
    oklch()
    Defines a color in the L*C*H* system with a perceptual correction
    rgb()
    Determines a color from the values ​​of Red, Green and Blue.
    rgba()
    Langue française
    Determines a color and its transparency from the values ​​of Red, Green, Blue and the Alpha value.

    At-rules:

    @color-profile
    Langue française
    Specifies a color profile that can then be used by the color() function.

    Descriptors :

    ⚠
    components
    Langue française
    Descriptor usable with the @color-profile at-rule.
    ⚠
    rendering-intent
    Langue française
    Descriptor usable with the @color-profile directive. Defines the method for converting from one color profile to another.