CSS cross-fade() Function

CSS cross-fade() Function

The CSS cross-fade() function blends two or more images into a single image using specified percentage weights.

It can be used to combine background images, create image overlays, and produce visual transitions between images. Browser support varies, and some browsers implement an older prefixed version with different syntax.

Syntax

cross-fade(image percentage, image percentage)
cross-fade(image percentage, image percentage, ...)

The standard cross-fade() syntax accepts a comma-separated list of images, each optionally followed by a percentage indicating its contribution to the result.

For example:

background-image: cross-fade(
  url("image-one.jpg") 50%,
  url("image-two.jpg") 50%
);

This requests an equal blend of two images.

Additional examples:

cross-fade(url("image-one.jpg") 75%, url("image-two.jpg") 25%)
cross-fade(url("image-one.jpg") 20%, url("image-two.jpg") 80%)
cross-fade(url("image-one.jpg") 40%, url("image-two.jpg") 60%)
cross-fade(url("image-one.jpg") 20%, url("image-two.jpg") 30%, url("image-three.jpg") 50%)

The function produces a CSS image value that can be used in properties accepting images, such as background-image.

Not all browsers support the standard syntax. The older -webkit-cross-fade() function uses a different argument format.

Parameters

The standard cross-fade() function accepts image values and optional percentage weights.

For example:

cross-fade(url("first.jpg") 70%, url("second.jpg") 30%)

The first image contributes 70%, and the second contributes 30%.

Percentages can be omitted:

cross-fade(url("first.jpg"), url("second.jpg"))

When no percentages are provided, the standard syntax distributes the weight equally between the images.

The function can also accept more than two images in the standard form.

How It Works

The cross-fade() function combines image content according to the weights assigned to each image.

For example:

cross-fade(url("first.jpg") 75%, url("second.jpg") 25%)

The result gives the first image a greater contribution than the second.

With equal percentages:

cross-fade(url("first.jpg") 50%, url("second.jpg") 50%)

Both images contribute equally to the result.

With the second image weighted more heavily:

cross-fade(url("first.jpg") 20%, url("second.jpg") 80%)

The second image becomes more prominent.

The function creates a blended image rather than adding two separate CSS background layers.

It does not automatically animate the blend. Animation requires a changing supported value or another technique.

Percentage Weights

Percentage weights determine how strongly each image contributes to the final image.

For example:

.background {
  background-image: cross-fade(
    url("first.jpg") 25%,
    url("second.jpg") 75%
  );
}

In the standard syntax, omitted weights are distributed among the images according to the remaining available percentage.

When the specified weights total more than 100%, they are normalized proportionally. When they total less than 100%, the remaining contribution is transparent.

For predictable results, explicitly assign weights that total 100%.

Multiple Images

The standard cross-fade() syntax allows more than two images to be combined.

For example:

.background {
  background-image: cross-fade(
    url("first.jpg") 20%,
    url("second.jpg") 30%,
    url("third.jpg") 50%
  );
}

In this example, the third image has the greatest contribution to the result.

Another example uses three equally weighted images:

.background {
  background-image: cross-fade(
    url("first.jpg"),
    url("second.jpg"),
    url("third.jpg")
  );
}

Each image receives an equal share of the total weight.

This capability belongs to the standard syntax and should not be confused with the older prefixed version, which accepts two images and one blend percentage.

Because browser implementations differ, test multiple-image blending before relying on it in production.

Transparency

The cross-fade() function can combine images that contain transparent pixels.

For example:

.background {
  background-image: cross-fade(
    url("graphic-one.png") 50%,
    url("graphic-two.png") 50%
  );
}

Transparent areas remain part of the image blending calculation.

When the combined percentage weights are less than 100%, the standard function also introduces transparency into the resulting image.

For example:

.background {
  background-color: #ffffff;
  background-image: cross-fade(
    url("graphic-one.png") 30%,
    url("graphic-two.png") 30%
  );
}

The specified weights total 60%, leaving a transparent contribution. The background color can show through that transparency.

For a fully weighted blend without additional transparency, use percentages totaling 100%.

Background Images

The cross-fade() function can be used with background-image to create a blended background.

For example:

.hero {
  background-image: cross-fade(
    url("background-one.jpg") 60%,
    url("background-two.jpg") 40%
  );
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
}

The function produces one blended image that is then positioned and sized by the background properties.

CSS gradients can also be supplied as image values:

.hero {
  background-image: cross-fade(
    linear-gradient(90deg, #0066cc, #00aaff) 50%,
    linear-gradient(90deg, #663399, #cc3399) 50%
  );
}

This requests a blend between two generated gradient images.

For broader browser compatibility, multiple background layers or an overlay pseudo-element may be a better choice.

Prefixed Syntax

Some browsers support the older -webkit-cross-fade() function rather than the standard cross-fade() syntax.

The prefixed version uses three arguments:

-webkit-cross-fade(first-image, second-image, percentage)

For example:

.background {
  background-image: -webkit-cross-fade(
    url("first.jpg"),
    url("second.jpg"),
    50%
  );
}

In the prefixed syntax, the percentage controls the contribution of the second image.

A value of 0% displays the first image, while 100% displays the second image.

Both examples request a blend with 75% contribution from the first image and 25% from the second.

The two syntaxes are not interchangeable. Simply adding a vendor prefix to the standard function name is not sufficient.

Example

This example blends two gradients using the standard syntax, with a prefixed declaration for browsers that support the older implementation.

HTML:

<div class="cross-fade-demo">
  <span>50% Image Blend</span>
</div>

CSS:

.cross-fade-demo {
  display: grid;
  place-items: center;
  min-height: 150px;
  padding: 20px;
  background-color: #0066cc;
  background-image: linear-gradient(90deg, #0066cc, #663399);
  background-image: -webkit-cross-fade(
    linear-gradient(90deg, #0066cc, #00aaff),
    linear-gradient(90deg, #663399, #cc3399),
    50%
  );
  color: #fff;
  font-weight: bold;
  text-align: center;
}
@supports (background-image: cross-fade(red 50%, blue 50%)) {
  .cross-fade-demo {
    background-image: cross-fade(
      linear-gradient(90deg, #0066cc, #00aaff) 50%,
      linear-gradient(90deg, #663399, #cc3399) 50%
    );
  }
}

Browsers supporting the standard syntax display the standard blend. Browsers supporting the prefixed version may display its equivalent blend.

Browsers supporting neither version display the fallback gradient.

The example uses gradients so no external image files are required.

Image Overlay Example

This example creates a translucent gradient effect by blending a gradient with a transparent image value.

HTML:

<div class="cross-fade-overlay">
  <span>Transparent Gradient Overlay</span>
</div>

CSS:

.cross-fade-overlay {
  display: grid;
  place-items: center;
  min-height: 150px;
  padding: 20px;
  background-color: #f2f5f9;
  background-image: linear-gradient(90deg, #99c2ff, #d5b3e6);
  background-image: -webkit-cross-fade(
    linear-gradient(90deg, #0066cc, #663399),
    linear-gradient(transparent, transparent),
    50%
  );
  color: #222;
  font-weight: bold;
  text-align: center;
}
@supports (background-image: cross-fade(red 50%, transparent 50%)) {
  .cross-fade-overlay {
    background-image: cross-fade(
      linear-gradient(90deg, #0066cc, #663399) 50%,
      transparent 50%
    );
  }
}

The blend reduces the opacity of the gradient, allowing the background color to show through.

The fallback uses a lighter gradient to approximate the intended appearance without requiring cross-fade() support.

Fallbacks

Because browser support is inconsistent, provide a fallback before using cross-fade().

For example:

.hero {
  background-image: linear-gradient(90deg, #0066cc, #663399);
  background-image: -webkit-cross-fade(
    linear-gradient(90deg, #0066cc, #00aaff),
    linear-gradient(90deg, #663399, #cc3399),
    50%
  );
}

A standard declaration can be added through feature detection:

@supports (background-image: cross-fade(red 50%, blue 50%)) {
  .hero {
    background-image: cross-fade(
      linear-gradient(90deg, #0066cc, #00aaff) 50%,
      linear-gradient(90deg, #663399, #cc3399) 50%
    );
  }
}

The @supports rule tests whether the browser recognizes the standard declaration.

Another fallback is to place two background layers or two positioned elements on top of each other and control their opacity.

That technique can be more appropriate when an animated cross-fade is required.

cross-fade() vs. Multiple Backgrounds

The cross-fade() function and multiple CSS backgrounds can both combine images, but they work differently.

For example, multiple backgrounds can be written as:

.hero {
  background-image:
    linear-gradient(rgba(0, 102, 204, 0.5), rgba(0, 102, 204, 0.5)),
    url("background.jpg");
}

This places a translucent gradient over an image.

Unlike cross-fade(), the images remain separate background layers rather than being combined into one image value.

Common Uses

The cross-fade() function can be useful for combining visual content.

For example:

.banner {
  background-image: cross-fade(
    url("banner-one.jpg") 65%,
    url("banner-two.jpg") 35%
  );
}

The result favors the first image while retaining a contribution from the second.

Limitations

The cross-fade() function has several important limitations.

• The standard syntax is not consistently supported across major browsers.
• The older -webkit-cross-fade() syntax differs from the standard syntax.
• The prefixed version accepts two images rather than an arbitrary number of images.
• Percentage weights affect image blending, not the dimensions of the element.
• The function does not automatically animate between images.
• Image sizing and positioning depend on the property where the result is used.
• Transparency can affect the appearance of the background beneath the blended image.
• Unsupported declarations are ignored, so fallbacks are important.

For example, this is the standard syntax:

background-image: cross-fade(
  url("first.jpg") 50%,
  url("second.jpg") 50%
);

The following is the older prefixed syntax:

background-image: -webkit-cross-fade(
  url("first.jpg"),
  url("second.jpg"),
  50%
);

Do not use the argument structure of one form with the function name of the other.

For production websites, use a supported fallback and test the result in the browsers your visitors use.

Browser Support

The standard CSS cross-fade() function has Limited availability and is not Baseline Widely available.

Some Chromium-based and WebKit-based browsers support the older -webkit-cross-fade() implementation, which uses different syntax.

Support for the standardized function and its multiple-image syntax is more limited.

For a fallback:

.example {
  background-image: linear-gradient(90deg, #0066cc, #663399);
  background-image: -webkit-cross-fade(
    linear-gradient(90deg, #0066cc, #00aaff),
    linear-gradient(90deg, #663399, #cc3399),
    50%
  );
}

For current compatibility information, visit Can I Use? and search for CSS cross-fade or CSS image functions.

Test the standard and prefixed forms separately because support for one does not guarantee support for the other.

Specifications

The cross-fade() function is defined in the CSS Images Module Level 4 .

The specification describes how multiple image values and percentage weights are combined to produce a single CSS image.

The older prefixed implementation is not equivalent to the complete standardized syntax.

Related CSS features include url(), linear-gradient(), image-set(), background-image, and opacity.