Blend

The blend parameter allows you to composite a color, text, or another image over your base image using various transformations known as blend modes. It must be set to enable the blend modes and other blending controls.

The default blend mode is overlay. See the blend mode parameter (blend-mode) for an explanation of each mode.

Blending with a Color

See the blend-color parameter (blend-color) for an explanation.

Blending with Images

You can also blend another image over your base image by passing an image URL to the blend parameter. When working with images, you will probably need to use some additional parameters to produce your desired composite. For example, it helps to use the blend size parameter, blend-size=inherit so that the overlay takes on the same size and cropping settings as the base image.

Note: Using an image containing transparency as your overlay may cause image artifacts. Consider using mark for these cases instead.

The image URL for the blend can be either absolute or relative, unless you want to perform additional imgix operations on the overlay itself. In that case, you will need to use an absolute URL. The overlay URL (with all such operations already applied), should be encoded and then passed to blend. You can use either UTF-8 or Base64 encoding; if you use Base 64, make sure to use the blend64 variant of the parameter.

These two URLs both resolve to the same blended image.

• UTF8 Encoding:

  https://assets.imgix.net/examples/butterfly.jpg?w=800&h=480&fit=crop&blend-size=inherit&blend-mode=screen&blend=https%3A%2F%2Fassets.imgix.net%2Fblog%2Fblog-blends.pdf%3Ffm%3Dpng%26page%3D3

• Base64 Encoding:

  https://assets.imgix.net/examples/butterfly.jpg?w=800&h=480&fit=crop&blend-size=inherit&blend-mode=screen&blend64=aHR0cHM6Ly9hc3NldHMuaW1naXgubmV0L2Jsb2cvYmxvZy1ibGVuZHMucGRmP2ZtPXBuZyZwYWdlPTM

An absolute URL has no restrictions in that it may reside on a separate host and path from the source image. If the URL is relative, the calculated absolute URL will have some restrictions based on the source type:

• Web Folder: Relative URLs must not resolve to an absolute URL outside of the base URL defined in the source
• Web Proxy: Relative URLs may resolve to to an absolute URL using any path with the host of the source URL
• Amazon S3:
  • Relative URLs must resolve to a resource within the same bucket
  • Relative URLs must not resolve to a path outsize of the prefix if one is set
  • The resolved URL will be signed using the same authentication credentials as the source URL

Blending with Text

With the Typesetting Endpoint, you can create multi-line text blocks that blend into your image in the same way a color or another image would. All of the blend modes and parameters can be used to control the position and style of the blend with the base image, and some imgix parameters can be applied to the text block as well.

The easiest way to get started with text overlays is to create the overlay first, using the txt parameters (this is a great use for the Sandbox). Then append any additional parameters needed to enhance the text (w in the example below). Finally, take the entire URL that’s output and run it through a URI encoder before appending it to the blend parameter.

Note: We recommend the following when creating text images for overlays.

• Use + signs in place of any spaces in the txt and txt-font parameters.
• Do not pre-encode any of the characters in the text string (the value for txt). Doing so will cause those characters to be double-encoded when the full ~text URL is encoded and the text will not display correctly.
• If you’re using the Sandbox to generate the initial text image, limit yourself to the A-Z a-z 0-9 . - _ characters to avoid double-encoding errors.

Edit in Sandbox

Here is the full URL for the image above, followed by a breakdown of the parameters applied to the image and the parameters applied to the text overlay.

https://assets.imgix.net/unsplash/unsplash006.jpg?w=640&h=400&usm=20&fit=crop&blend-mode=normal&blend-alpha=80&blend-x=30&blend-y=20&blend=https%3A%2F%2Fassets.imgix.net%2F~text%3Ftxt-color%3D9fb64d%26txt-font%3DAvenir%2BNext%2BHeavy%26txt-shad%3D20%26txt-size%3D32%26w%3D580%26txt%3Di%2Bthank%2Byou%2Bgod%2Bfor%2Bmost%2Bthis%2Bamazing%2Bday%3Afor%2Bthe%2Bleaping%2Bgreenly%2Bspirits%2Bof%2Btrees%2B-e.e.%2Bcummings

For a more in-depth exploration of how to use ~text outputs as layers in composite images, read the Typesetting tutorial.

Parameter Priority

When using multiple parameters to overlay images, parameter priority will dictate which parameter is shown over another. The order is as follows:

• text
• mark
• blend

A parameter with a higher priority will be shown over parameters of a lower priority, e.g. text will always be shown above mark, and mark above blend.