Documentation

blend Blend

Prefer Base64 Variant

imgix recommends using the Base64 variant version of this parameter to make encoding values easier.

Blend allows for a color or an image to composite over your current image using various transformations known as blend modes. The default blend mode is overlay. To specify a different mode use the blend mode bm parameter.

Blend Color

To blend with a solid color over your entire image, the blend parameter can take either a 3 (RGB), 6 (RRGGBB) or 8 digit (AARRGGBB) hexadecimal value. The first two digits of an 8 digit hex value represent the color’s alpha transparency.

Blend Images

You can set an image URL to the blend parameter, and it will composite over your main image. When working with images, you may need to use some additional parameters to produce a desired composited effect. In many cases, it helps to use the blend size parameter, bs=inherit.

Note: If an image containing transparency is set to the blend parameter, image artifacts may appear. Please consider using mark for these cases.

The image URL for the blend can be either absolute or relative. To perform imgix operations on a blend image, you will need to use an absolute URL. You may need to use encoded values to perform the blend image’s imgix operations. Only UTF-8 character encoding is accepted.

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 outsize 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

Blend 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 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 txtfont 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 imgix Sandbox to generate the initial text image, limit yourself to the A-Z a-z 0-9 . - _ characters to avoid double-encoding errors.

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&bm=normal&balph=80&bx=30&by=20&blend=https%3A%2F%2Fassets.imgix.net%2F~text%3Ftxtclr%3D9fb64d%26txtfont%3DAvenir%2BNext%2BHeavy%26txtshad%3D20%26txtsize%3D32%26w%3D580%26txt%3Di%2Bthank%2Byou%2Bgod%2Bfor%2Bmost%2Bthis%2Bamazing%2Bday%3Afor%2Bthe%2Bleaping%2Bgreenly%2Bspirits%2Bof%2Btrees%2B-e.e.%2Bcummings

Image Parameters Text Watermark Parameters1
w-640 txtsize=32
h=400 w=580
fit=crop txtshad=20
usm=20 txtcolor=9fb64d
blend=* txtfont=Avenir+Next+Heavy
bm=normal txt=i+thank+You+God+for+most+t
balph=80 his+amazing+day:for+the+leapin
bx=30 g+greenly+spirits+of+trees+-
by-20 +e.e.+cummings

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