CSS cross-fade() Function

The cross-fade() function allows you to blend two or more images together.

It can be used anywhere an image is accepted in CSS. This includes properties such as background-image, list-style-image, and border-image.

However, at the time of writing, there is a significant discrepancy between the official W3C specification and what browsers have actually implemented. Most modern browsers (like Chrome, Safari, and Edge) support an older, non-standard syntax, often requiring a -webkit- prefix.

Because of this, it is highly recommended to understand both the currently implemented syntax (so you can use it today) and the official specification syntax (to future-proof your code as browsers update).

The Implemented Syntax (Current Browser Support)

To get cross-fade() working in most browsers today, you must use the older syntax. This syntax strictly accepts exactly two images, followed by a single percentage at the end.

The percentage dictates how much of the second image is visible. For example, a value of 75% means the second image is at 75% opacity, and the first image makes up the remaining 25%.

You will also likely need to include the -webkit-cross-fade() prefixed version as a fallback for maximum compatibility.

Here's an example:

The above example was the best way to get cross-fade() to work at the time of writing. It's possible that you're viewing this page in the future, and a new syntax has been implemented. See below for an example of the new W3C specification syntax (which should have more browser support as time goes on).

The Official W3C Specification Syntax

The official CSS Images Module Level 4 specification outlines a much more flexible syntax. Instead of a single percentage at the end, you attach a percentage directly to each individual image.

This allows you to blend more than two images together. If you omit a percentage for an image, the browser is supposed to automatically calculate the remaining percentage so that they all add up to 100%.

Here is an example of the official specification syntax:

Note: Depending on your browser, this example may not render correctly until the browser fully supports the Level 4 specification.

Official Syntax

The official syntax of the cross-fade() function (as per the Level 4 specification) is as follows:

Where <image-percentage> is defined as:

Possible Values

As indicated in the official syntax, the cross-fade() function accepts the following values:

image

An image to be blended. This can be a URL to an external image (e.g., url('image.jpg')), a CSS gradient, or any other valid CSS image data type.

percentage

An optional percentage that defines the opacity of the image in the final blend. 0% means the image is completely transparent, while 100% means it is fully opaque.

CSS Specifications

• The cross-fade() function is defined in CSS Image Values and Replaced Content Module Level 4 (Editor’s Draft)

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.