Conditional transformations

Cloudinary supports conditional transformations for images, where a transformation is only applied if a specified condition is met, for example, when the image's width is greater than 300 pixels. This section consists of the following topics:

On this page:

Specifying conditions

To specify a condition to be met before applying a transformation use the if parameter (also if in URLs). The if parameter accepts a string value detailing the condition to evaluate, and is given in the following format:

if_<image characteristic>_<operator>_<image characteristic value>

Where:

  • image characteristic - the characteristic of the image to evaluate, for example 'w' (or 'width' in SDKs).
  • operator - the comparison operator for the comparison, for example 'lt' for 'less than' (or '<' in SDKs).
  • image characteristic value - the value of the characteristic or a different image characteristic.

See examples below.

Supported image characteristics:

Characteristic Description
w (also width in SDKs) The image's current width.
iw The image's initial width.
h (also height in SDKs) The image's current height.
ih The image's initial height.
ar (also aspect_ratio in SDKs) The aspect ratio of the image. The compared value can be either decimal (e.g., 1.5) or a ratio (e.g., 3:4).
tar (also trimmed_aspect_ratio in SDKs) The aspect ratio of the image IF it was trimmed (using the 'trim' effect) without actually trimming the image. The compared value can be either decimal (e.g., 1.5) or a ratio (e.g., 3:4).
cp The current page in the image/document.
pc (also page_count in SDKs) The total number of pages in the image/document.
fc (also face_count in SDKs) The total number of detected faces in the image.
ils The likelihood that the image is an illustration (as opposed to a photo).
Supported values: 0 (photo) to 1 (illustration)
ctx A context value assigned to an image.
tags The set of tags assigned to the image.
Used with the in or nin operators.
Note: The syntax for this characteristic is slightly different:
if_!<string1:string2:stringN>!_in_tags, where the : delimiter denotes AND.

Supported operators:

URL SDK symbol Description
eq = Equal to
ne != Not equal to
lt < Less than
gt > Greater than
lte <= Less than or equal to
gte >= Greater than or equal to
in|nin in|nin Included in | Not included in
Compares a set of strings against the tags characteristic or against another set of strings. See examples.

When working with the Cloudinary SDKs, you can specify the condition using the SDK characteristic names and operator symbols, or you can specify it using the URL format. For example, both of the following are valid:

  • { if: "w_gt_1000", crop: "scale", width: 500}
  • { if: "width > 1000", crop: "scale", width: 500}

Supported conditional transformation parameters and flags

  • All transformation parameters can be used with conditions except the following: page, default_image, color_space, delay

  • Only the following flags are supported with conditional transformations: layer_apply, region_relative, relative, progressive, cutter, png8, attachment, awebp, lossy

Conditional transformation examples

  • Conditional text overlay based on width This example limits an image size to a width of 300 pixels using the limit crop mode, and then uses a conditional transformation to add a text caption only to images whose initial width was wider than 300 and were scaled down (if_w_gt_300):

    URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
    URL:
    https://res.cloudinary.com/demo/image/upload/c_limit,w_300/if_iw_gt_300,co_white,g_south_east,l_text:Arial_15_bold:Image scaled down to 300px/sample.jpg
    Ruby:
    cl_image_tag("sample.jpg", :transformation=>[
  {:width=>300, :crop=>"limit"},
  {:if=>"iw_gt_300", :color=>"white", :gravity=>"south_east", :overlay=>{:font_family=>"Arial", :font_size=>15, :font_weight=>"bold", :text=>"Image%20scaled%20down%20to%20300px"}}
  ])
    PHP:
    cl_image_tag("sample.jpg", array("transformation"=>array(
  array("width"=>300, "crop"=>"limit"),
  array("if"=>"iw_gt_300", "color"=>"white", "gravity"=>"south_east", "overlay"=>array("font_family"=>"Arial", "font_size"=>15, "font_weight"=>"bold", "text"=>"Image%20scaled%20down%20to%20300px"))
  )))
    Python:
    CloudinaryImage("sample.jpg").image(transformation=[
  {'width': 300, 'crop': "limit"},
  {'if': "iw_gt_300", 'color': "white", 'gravity': "south_east", 'overlay': {'font_family': "Arial", 'font_size': 15, 'font_weight': "bold", 'text': "Image%20scaled%20down%20to%20300px"}}
  ])
    Node.js:
    cloudinary.image("sample.jpg", {transformation: [
  {width: 300, crop: "limit"},
  {if: "iw_gt_300", color: "white", gravity: "south_east", overlay: {font_family: "Arial", font_size: 15, font_weight: "bold", text: "Image%20scaled%20down%20to%20300px"}}
  ]})
    Java:
    cloudinary.url().transformation(new Transformation()
  .width(300).crop("limit").chain()
  .if("iw_gt_300").color("white").gravity("south_east").overlay(new TextLayer().fontFamily("Arial").fontSize(15).fontWeight("bold").text("Image%20scaled%20down%20to%20300px"))).imageTag("sample.jpg");
    JS:
    cloudinary.imageTag('sample.jpg', {transformation: [
  {width: 300, crop: "limit"},
  {if: "iw_gt_300", color: "white", gravity: "south_east", overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(15).fontWeight("bold").text("Image%20scaled%20down%20to%20300px")}
  ]}).toHtml();
    jQuery:
    $.cloudinary.image("sample.jpg", {transformation: [
  {width: 300, crop: "limit"},
  {if: "iw_gt_300", color: "white", gravity: "south_east", overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(15).fontWeight("bold").text("Image%20scaled%20down%20to%20300px")}
  ]})
    React:
    <Image publicId="sample.jpg" >
  <Transformation width="300" crop="limit" />
  <Transformation if="iw_gt_300" color="white" gravity="south_east" overlay={{fontFamily: "Arial", fontSize: 15, fontWeight: "bold", text: "Image%20scaled%20down%20to%20300px"}} />
</Image>
    Vue.js:
    <cld-image publicId="sample.jpg" >
  <cld-transformation width="300" crop="limit" />
  <cld-transformation if="iw_gt_300" color="white" gravity="south_east" overlay={{fontFamily: "Arial", fontSize: 15, fontWeight: "bold", text: "Image%20scaled%20down%20to%20300px"}} />
</cld-image>
    Angular:
    <cl-image public-id="sample.jpg" >
  <cl-transformation width="300" crop="limit">
  </cl-transformation>
  <cl-transformation if="iw_gt_300" color="white" gravity="south_east" overlay="text:Arial_15_bold:Image%20scaled%20down%20to%20300px">
  </cl-transformation>
</cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(300).Crop("limit").Chain()
  .If("iw_gt_300").Color("white").Gravity("south_east").Overlay(new TextLayer().FontFamily("Arial").FontSize(15).FontWeight("bold").Text("Image%20scaled%20down%20to%20300px"))).BuildImageTag("sample.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation()
  .width(300).crop("limit").chain()
  .if("iw_gt_300").color("white").gravity("south_east").overlay(new TextLayer().fontFamily("Arial").fontSize(15).fontWeight("bold").text("Image%20scaled%20down%20to%20300px"))).generate("sample.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(300).setCrop("limit").chain()
  .setIf("iw_gt_300").setColor("white").setGravity("south_east").setOverlay("text:Arial_15_bold:Image%20scaled%20down%20to%20300px")).generate("sample.jpg")!, cloudinary: cloudinary)
    Conditional transformation

  • Conditional cropping mode based on illustration score This example ensures that uploaded graphics such as logos are never cut off, even if the art design changes its aspect ratio, but photos will always fill the full space available. Using the ils conditional characteristic, the cloudinary_icon is cropped using the pad method and the sample photo is cropped using the fill method:

    URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
    URL:
    https://res.cloudinary.com/demo/image/upload/if_ils_gt_0.5,w_120,h_150,c_pad/if_else,w_120,h_150,c_fill/cloudinary_icon.jpg
    Ruby:
    cl_image_tag("cloudinary_icon.jpg", :transformation=>[
  {:if=>"ils_gt_0.5", :width=>120, :height=>150, :crop=>"pad"},
  {:if=>"else", :width=>120, :height=>150, :crop=>"fill"}
  ])
    PHP:
    cl_image_tag("cloudinary_icon.jpg", array("transformation"=>array(
  array("if"=>"ils_gt_0.5", "width"=>120, "height"=>150, "crop"=>"pad"),
  array("if"=>"else", "width"=>120, "height"=>150, "crop"=>"fill")
  )))
    Python:
    CloudinaryImage("cloudinary_icon.jpg").image(transformation=[
  {'if': "ils_gt_0.5", 'width': 120, 'height': 150, 'crop': "pad"},
  {'if': "else", 'width': 120, 'height': 150, 'crop': "fill"}
  ])
    Node.js:
    cloudinary.image("cloudinary_icon.jpg", {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]})
    Java:
    cloudinary.url().transformation(new Transformation()
  .if("ils_gt_0.5").width(120).height(150).crop("pad").chain()
  .if("else").width(120).height(150).crop("fill")).imageTag("cloudinary_icon.jpg");
    JS:
    cloudinary.imageTag('cloudinary_icon.jpg', {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]}).toHtml();
    jQuery:
    $.cloudinary.image("cloudinary_icon.jpg", {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]})
    React:
    <Image publicId="cloudinary_icon.jpg" >
  <Transformation if="ils_gt_0.5" width="120" height="150" crop="pad" />
  <Transformation if="else" width="120" height="150" crop="fill" />
</Image>
    Vue.js:
    <cld-image publicId="cloudinary_icon.jpg" >
  <cld-transformation if="ils_gt_0.5" width="120" height="150" crop="pad" />
  <cld-transformation if="else" width="120" height="150" crop="fill" />
</cld-image>
    Angular:
    <cl-image public-id="cloudinary_icon.jpg" >
  <cl-transformation if="ils_gt_0.5" width="120" height="150" crop="pad">
  </cl-transformation>
  <cl-transformation if="else" width="120" height="150" crop="fill">
  </cl-transformation>
</cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("ils_gt_0.5").Width(120).Height(150).Crop("pad").Chain()
  .If("else").Width(120).Height(150).Crop("fill")).BuildImageTag("cloudinary_icon.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation()
  .if("ils_gt_0.5").width(120).height(150).crop("pad").chain()
  .if("else").width(120).height(150).crop("fill")).generate("cloudinary_icon.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("ils_gt_0.5").setWidth(120).setHeight(150).setCrop("pad").chain()
  .setIf("else").setWidth(120).setHeight(150).setCrop("fill")).generate("cloudinary_icon.jpg")!, cloudinary: cloudinary)
    icon with conditional pad cropping
    URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
    URL:
    https://res.cloudinary.com/demo/image/upload/if_ils_gt_0.5,w_120,h_150,c_pad/if_else,w_120,h_150,c_fill/sample.jpg
    Ruby:
    cl_image_tag("sample.jpg", :transformation=>[
  {:if=>"ils_gt_0.5", :width=>120, :height=>150, :crop=>"pad"},
  {:if=>"else", :width=>120, :height=>150, :crop=>"fill"}
  ])
    PHP:
    cl_image_tag("sample.jpg", array("transformation"=>array(
  array("if"=>"ils_gt_0.5", "width"=>120, "height"=>150, "crop"=>"pad"),
  array("if"=>"else", "width"=>120, "height"=>150, "crop"=>"fill")
  )))
    Python:
    CloudinaryImage("sample.jpg").image(transformation=[
  {'if': "ils_gt_0.5", 'width': 120, 'height': 150, 'crop': "pad"},
  {'if': "else", 'width': 120, 'height': 150, 'crop': "fill"}
  ])
    Node.js:
    cloudinary.image("sample.jpg", {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]})
    Java:
    cloudinary.url().transformation(new Transformation()
  .if("ils_gt_0.5").width(120).height(150).crop("pad").chain()
  .if("else").width(120).height(150).crop("fill")).imageTag("sample.jpg");
    JS:
    cloudinary.imageTag('sample.jpg', {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]}).toHtml();
    jQuery:
    $.cloudinary.image("sample.jpg", {transformation: [
  {if: "ils_gt_0.5", width: 120, height: 150, crop: "pad"},
  {if: "else", width: 120, height: 150, crop: "fill"}
  ]})
    React:
    <Image publicId="sample.jpg" >
  <Transformation if="ils_gt_0.5" width="120" height="150" crop="pad" />
  <Transformation if="else" width="120" height="150" crop="fill" />
</Image>
    Vue.js:
    <cld-image publicId="sample.jpg" >
  <cld-transformation if="ils_gt_0.5" width="120" height="150" crop="pad" />
  <cld-transformation if="else" width="120" height="150" crop="fill" />
</cld-image>
    Angular:
    <cl-image public-id="sample.jpg" >
  <cl-transformation if="ils_gt_0.5" width="120" height="150" crop="pad">
  </cl-transformation>
  <cl-transformation if="else" width="120" height="150" crop="fill">
  </cl-transformation>
</cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("ils_gt_0.5").Width(120).Height(150).Crop("pad").Chain()
  .If("else").Width(120).Height(150).Crop("fill")).BuildImageTag("sample.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation()
  .if("ils_gt_0.5").width(120).height(150).crop("pad").chain()
  .if("else").width(120).height(150).crop("fill")).generate("sample.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("ils_gt_0.5").setWidth(120).setHeight(150).setCrop("pad").chain()
  .setIf("else").setWidth(120).setHeight(150).setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
    photo with conditional fill cropping

  • Conditional resize based on a context value This example resizes an image to a 200*200 square image (using g_auto cropping) if it has a context key named 'productType' with the value 'shoes'.

    URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
    URL:
    https://res.cloudinary.com/demo/image/upload/if_ctx:!productType!_eq_!shoes!,w_200,ar_1:1,c_fill,g_auto/sunset_shoes.jpg
    Ruby:
    cl_image_tag("sunset_shoes.jpg", :if=>"ctx:!productType!_eq_!shoes!", :width=>200, :aspect_ratio=>"1:1", :gravity=>"auto", :crop=>"fill")
    PHP:
    cl_image_tag("sunset_shoes.jpg", array("if"=>"ctx:!productType!_eq_!shoes!", "width"=>200, "aspect_ratio"=>"1:1", "gravity"=>"auto", "crop"=>"fill"))
    Python:
    CloudinaryImage("sunset_shoes.jpg").image(if="ctx:!productType!_eq_!shoes!", width=200, aspect_ratio="1:1", gravity="auto", crop="fill")
    Node.js:
    cloudinary.image("sunset_shoes.jpg", {if: "ctx:!productType!_eq_!shoes!", width: 200, aspect_ratio: "1:1", gravity: "auto", crop: "fill"})
    Java:
    cloudinary.url().transformation(new Transformation().if("ctx:!productType!_eq_!shoes!").width(200).aspectRatio("1:1").gravity("auto").crop("fill")).imageTag("sunset_shoes.jpg");
    JS:
    cloudinary.imageTag('sunset_shoes.jpg', {if: "ctx:!productType!_eq_!shoes!", width: 200, aspectRatio: "1:1", gravity: "auto", crop: "fill"}).toHtml();
    jQuery:
    $.cloudinary.image("sunset_shoes.jpg", {if: "ctx:!productType!_eq_!shoes!", width: 200, aspect_ratio: "1:1", gravity: "auto", crop: "fill"})
    React:
    <Image publicId="sunset_shoes.jpg" >
  <Transformation if="ctx:!productType!_eq_!shoes!" width="200" aspectRatio="1:1" gravity="auto" crop="fill" />
</Image>
    Vue.js:
    <cld-image publicId="sunset_shoes.jpg" >
  <cld-transformation if="ctx:!productType!_eq_!shoes!" width="200" aspectRatio="1:1" gravity="auto" crop="fill" />
</cld-image>
    Angular:
    <cl-image public-id="sunset_shoes.jpg" >
  <cl-transformation if="ctx:!productType!_eq_!shoes!" width="200" aspect-ratio="1:1" gravity="auto" crop="fill">
  </cl-transformation>
</cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation().If("ctx:!productType!_eq_!shoes!").Width(200).AspectRatio("1:1").Gravity("auto").Crop("fill")).BuildImageTag("sunset_shoes.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation().if("ctx:!productType!_eq_!shoes!").width(200).aspectRatio("1:1").gravity("auto").crop("fill")).generate("sunset_shoes.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setIf("ctx:!productType!_eq_!shoes!").setWidth(200).setAspectRatio("1:1").setGravity("auto").setCrop("fill")).generate("sunset_shoes.jpg")!, cloudinary: cloudinary)
    Crop images with a specified context value

  • Conditional image overlay based on tags This example adds a sale icon to a product image if both the strings ‘sale’ and ‘in_stock” are among the tags assigned to the image:

    URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
    URL:
    https://res.cloudinary.com/demo/image/upload/if_!sale:in_stock!_in_tags,l_sale_icon,w_180,g_south_east,x_30,y_30/w_250/backpack.jpg
    Ruby:
    cl_image_tag("backpack.jpg", :transformation=>[
  {:if=>"!sale:in_stock!_in_tags", :overlay=>"sale_icon", :width=>180, :gravity=>"south_east", :x=>30, :y=>30},
  {:width=>250, :crop=>"scale"}
  ])
    PHP:
    cl_image_tag("backpack.jpg", array("transformation"=>array(
  array("if"=>"!sale:in_stock!_in_tags", "overlay"=>"sale_icon", "width"=>180, "gravity"=>"south_east", "x"=>30, "y"=>30),
  array("width"=>250, "crop"=>"scale")
  )))
    Python:
    CloudinaryImage("backpack.jpg").image(transformation=[
  {'if': "!sale:in_stock!_in_tags", 'overlay': "sale_icon", 'width': 180, 'gravity': "south_east", 'x': 30, 'y': 30},
  {'width': 250, 'crop': "scale"}
  ])
    Node.js:
    cloudinary.image("backpack.jpg", {transformation: [
  {if: "!sale:in_stock!_in_tags", overlay: "sale_icon", width: 180, gravity: "south_east", x: 30, y: 30},
  {width: 250, crop: "scale"}
  ]})
    Java:
    cloudinary.url().transformation(new Transformation()
  .if("!sale:in_stock!_in_tags").overlay(new Layer().publicId("sale_icon")).width(180).gravity("south_east").x(30).y(30).chain()
  .width(250).crop("scale")).imageTag("backpack.jpg");
    JS:
    cloudinary.imageTag('backpack.jpg', {transformation: [
  {if: "!sale:in_stock!_in_tags", overlay: new cloudinary.Layer().publicId("sale_icon"), width: 180, gravity: "south_east", x: 30, y: 30},
  {width: 250, crop: "scale"}
  ]}).toHtml();
    jQuery:
    $.cloudinary.image("backpack.jpg", {transformation: [
  {if: "!sale:in_stock!_in_tags", overlay: new cloudinary.Layer().publicId("sale_icon"), width: 180, gravity: "south_east", x: 30, y: 30},
  {width: 250, crop: "scale"}
  ]})
    React:
    <Image publicId="backpack.jpg" >
  <Transformation if="!sale:in_stock!_in_tags" overlay="sale_icon" width="180" gravity="south_east" x="30" y="30" />
  <Transformation width="250" crop="scale" />
</Image>
    Vue.js:
    <cld-image publicId="backpack.jpg" >
  <cld-transformation if="!sale:in_stock!_in_tags" overlay="sale_icon" width="180" gravity="south_east" x="30" y="30" />
  <cld-transformation width="250" crop="scale" />
</cld-image>
    Angular:
    <cl-image public-id="backpack.jpg" >
  <cl-transformation if="!sale:in_stock!_in_tags" overlay="sale_icon" width="180" gravity="south_east" x="30" y="30">
  </cl-transformation>
  <cl-transformation width="250" crop="scale">
  </cl-transformation>
</cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("!sale:in_stock!_in_tags").Overlay(new Layer().PublicId("sale_icon")).Width(180).Gravity("south_east").X(30).Y(30).Chain()
  .Width(250).Crop("scale")).BuildImageTag("backpack.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation()
  .if("!sale:in_stock!_in_tags").overlay(new Layer().publicId("sale_icon")).width(180).gravity("south_east").x(30).y(30).chain()
  .width(250).crop("scale")).generate("backpack.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("!sale:in_stock!_in_tags").setOverlay("sale_icon").setWidth(180).setGravity("south_east").setX(30).setY(30).chain()
  .setWidth(250).setCrop("scale")).generate("backpack.jpg")!, cloudinary: cloudinary)
    product with conditional sale icon

Notes

  • The position of the if parameter inside a transformation component doesn't matter and it applies to the whole component (a single transformation between a pair of slashes).
  • For the w, h, cp and ar parameters, the values refer to the current image status in the transformation chain (i.e., if transformations have already been applied to the image), while iw, ih, fc and pc always refer to the original image.
  • dpr is not supported as a conditional transformation with the cp and ar characteristics. Additionally, w and h are supported with dpr as long as they are still equal to iw or ih when the condition is evaluated.
  • The ar (aspect ratio) parameter should be compared using 'greater than' or 'less than' rather than with 'equals'. This is because the width and height values are given as integers and not floating point values, leading to an "almost exact" calculated aspect ratio.
  • Conditions are not supported for video resources.

Multiple conditions

You can specify multiple conditions to evaluate by joining the conditions with a logical conjunction operator.

Operator Description
and The transformations are applied only if BOTH conditions evaluate as true.
or The transformations are applied if EITHER condition evaluates as true.

Note
There is a precedence for the evaluation of operators: 'and' is evaluated before 'or'.

For example, to crop the sample image to a width of 300 pixels and a height of 200 pixels, only if the aspect ratio is greater than 3:4, the width is greater than 300, and the height is greater than 200 (if_ar_gt_3:4_and_w_gt_300_and_h_gt_200):

URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
URL:
https://res.cloudinary.com/demo/image/upload/if_ar_gt_3:4_and_w_gt_300_and_h_gt_200,c_crop,w_300,h_200/sample.jpg
Ruby:
cl_image_tag("sample.jpg", :if=>"ar_gt_3:4_and_w_gt_300_and_h_gt_200", :width=>300, :height=>200, :crop=>"crop")
PHP:
cl_image_tag("sample.jpg", array("if"=>"ar_gt_3:4_and_w_gt_300_and_h_gt_200", "width"=>300, "height"=>200, "crop"=>"crop"))
Python:
CloudinaryImage("sample.jpg").image(if="ar_gt_3:4_and_w_gt_300_and_h_gt_200", width=300, height=200, crop="crop")
Node.js:
cloudinary.image("sample.jpg", {if: "ar_gt_3:4_and_w_gt_300_and_h_gt_200", width: 300, height: 200, crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().if("ar_gt_3:4_and_w_gt_300_and_h_gt_200").width(300).height(200).crop("crop")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {if: "ar_gt_3:4_and_w_gt_300_and_h_gt_200", width: 300, height: 200, crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {if: "ar_gt_3:4_and_w_gt_300_and_h_gt_200", width: 300, height: 200, crop: "crop"})
React:
<Image publicId="sample.jpg" >
  <Transformation if="ar_gt_3:4_and_w_gt_300_and_h_gt_200" width="300" height="200" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
  <cld-transformation if="ar_gt_3:4_and_w_gt_300_and_h_gt_200" width="300" height="200" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
  <cl-transformation if="ar_gt_3:4_and_w_gt_300_and_h_gt_200" width="300" height="200" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().If("ar_gt_3:4_and_w_gt_300_and_h_gt_200").Width(300).Height(200).Crop("crop")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().if("ar_gt_3:4_and_w_gt_300_and_h_gt_200").width(300).height(200).crop("crop")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setIf("ar_gt_3:4_and_w_gt_300_and_h_gt_200").setWidth(300).setHeight(200).setCrop("crop")).generate("sample.jpg")!, cloudinary: cloudinary)
Multiple conditions

Multiple conditional transformations

To set a condition for applying multiple transformations (in the form of chained transformation components), add an if_end parameter to the last transformation component in the chain. In order to avoid ambiguity when applying a condition on multiple chained components, the components with the if and the if_end parameters should not have additional transformation instructions. For example:

  • Wrong: if_w_gt_500,c_crop,h_200,w_300,e_red:50/e_blur/if_end
  • Right: if_w_gt_500/c_crop,h_200,w_300/e_red:50/e_blur/if_end

For example, if you allocate space on your page for an image with a width of 600px, you can conditionally add a blurred background for images whose width is less than 600px:

URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
URL:
https://res.cloudinary.com/demo/image/upload/if_w_lt_600/l_text:Arial_20:Image shown in full scale,co_white,g_south_east/c_scale,e_blur:400,u_small_dinosaur,w_600/if_end/v1458729247/small_dinosaur.jpg
Ruby:
cl_image_tag("small_dinosaur.jpg", :transformation=>[
  {:if=>"w_lt_600"},
  {:overlay=>{:font_family=>"Arial", :font_size=>20, :text=>"Image%20shown%20in%20full%20scale"}, :color=>"white", :gravity=>"south_east"},
  {:effect=>"blur:400", :underlay=>"small_dinosaur", :width=>600, :crop=>"scale"},
  {:if=>"end"}
  ])
PHP:
cl_image_tag("small_dinosaur.jpg", array("transformation"=>array(
  array("if"=>"w_lt_600"),
  array("overlay"=>array("font_family"=>"Arial", "font_size"=>20, "text"=>"Image%20shown%20in%20full%20scale"), "color"=>"white", "gravity"=>"south_east"),
  array("effect"=>"blur:400", "underlay"=>"small_dinosaur", "width"=>600, "crop"=>"scale"),
  array("if"=>"end")
  )))
Python:
CloudinaryImage("small_dinosaur.jpg").image(transformation=[
  {'if': "w_lt_600"},
  {'overlay': {'font_family': "Arial", 'font_size': 20, 'text': "Image%20shown%20in%20full%20scale"}, 'color': "white", 'gravity': "south_east"},
  {'effect': "blur:400", 'underlay': "small_dinosaur", 'width': 600, 'crop': "scale"},
  {'if': "end"}
  ])
Node.js:
cloudinary.image("small_dinosaur.jpg", {transformation: [
  {if: "w_lt_600"},
  {overlay: {font_family: "Arial", font_size: 20, text: "Image%20shown%20in%20full%20scale"}, color: "white", gravity: "south_east"},
  {effect: "blur:400", underlay: "small_dinosaur", width: 600, crop: "scale"},
  {if: "end"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .if("w_lt_600").chain()
  .overlay(new TextLayer().fontFamily("Arial").fontSize(20).text("Image%20shown%20in%20full%20scale")).color("white").gravity("south_east").chain()
  .effect("blur:400").underlay(new Layer().publicId("small_dinosaur")).width(600).crop("scale").chain()
  .if("end")).imageTag("small_dinosaur.jpg");
JS:
cloudinary.imageTag('small_dinosaur.jpg', {transformation: [
  {if: "w_lt_600"},
  {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(20).text("Image%20shown%20in%20full%20scale"), color: "white", gravity: "south_east"},
  {effect: "blur:400", underlay: new cloudinary.Layer().publicId("small_dinosaur"), width: 600, crop: "scale"},
  {if: "end"}
  ]}).toHtml();
jQuery:
$.cloudinary.image("small_dinosaur.jpg", {transformation: [
  {if: "w_lt_600"},
  {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(20).text("Image%20shown%20in%20full%20scale"), color: "white", gravity: "south_east"},
  {effect: "blur:400", underlay: new cloudinary.Layer().publicId("small_dinosaur"), width: 600, crop: "scale"},
  {if: "end"}
  ]})
React:
<Image publicId="small_dinosaur.jpg" >
  <Transformation if="w_lt_600" />
  <Transformation overlay={{fontFamily: "Arial", fontSize: 20, text: "Image%20shown%20in%20full%20scale"}} color="white" gravity="south_east" />
  <Transformation effect="blur:400" underlay="small_dinosaur" width="600" crop="scale" />
  <Transformation if="end" />
</Image>
Vue.js:
<cld-image publicId="small_dinosaur.jpg" >
  <cld-transformation if="w_lt_600" />
  <cld-transformation overlay={{fontFamily: "Arial", fontSize: 20, text: "Image%20shown%20in%20full%20scale"}} color="white" gravity="south_east" />
  <cld-transformation effect="blur:400" underlay="small_dinosaur" width="600" crop="scale" />
  <cld-transformation if="end" />
</cld-image>
Angular:
<cl-image public-id="small_dinosaur.jpg" >
  <cl-transformation if="w_lt_600">
  </cl-transformation>
  <cl-transformation overlay="text:Arial_20:Image%20shown%20in%20full%20scale" color="white" gravity="south_east">
  </cl-transformation>
  <cl-transformation effect="blur:400" underlay="small_dinosaur" width="600" crop="scale">
  </cl-transformation>
  <cl-transformation if="end">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("w_lt_600").Chain()
  .Overlay(new TextLayer().FontFamily("Arial").FontSize(20).Text("Image%20shown%20in%20full%20scale")).Color("white").Gravity("south_east").Chain()
  .Effect("blur:400").Underlay(new Layer().PublicId("small_dinosaur")).Width(600).Crop("scale").Chain()
  .If("end")).BuildImageTag("small_dinosaur.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .if("w_lt_600").chain()
  .overlay(new TextLayer().fontFamily("Arial").fontSize(20).text("Image%20shown%20in%20full%20scale")).color("white").gravity("south_east").chain()
  .effect("blur:400").underlay(new Layer().publicId("small_dinosaur")).width(600).crop("scale").chain()
  .if("end")).generate("small_dinosaur.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("w_lt_600").chain()
  .setOverlay("text:Arial_20:Image%20shown%20in%20full%20scale").setColor("white").setGravity("south_east").chain()
  .setEffect("blur:400").setUnderlay("small_dinosaur").setWidth(600).setCrop("scale").chain()
  .setIf("end")).generate("small_dinosaur.jpg")!, cloudinary: cloudinary)
conditional background

Notes

  • Multiple separate conditions can be used in a single URL, but only one per transformation component.
  • Cloudinary supports a single level of nested 'if' conditions.
  • A named transformation must not be placed in the same transformation component as its condition (e.g., if_w_eq_h,t_trans is not supported). Apply the condition on the named transformation by using a chained transformation (e.g., if_w_eq_h/t_trans/if_end).

Else branch transformations

You can also specify a transformation that is applied in the case that the initial condition is evaluated as negative (and hence the transformations associated with the condition are not applied), by using the if_else parameter to specify this fallback transformation.

For example, to fill an image to a width of 80 pixels and a height of 120 pixels if the original image has a width less than or equal to 200 pixels (the condition: if_w_lte_200,c_fill,h_120,w_80), and to fill the image to a width of 100 pixels and a height of 150 pixels if the original image has a width greater than 200 pixels (the fallback: if_else,c_fill,h_90,w_100):

URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
URL:
https://res.cloudinary.com/demo/image/upload/if_w_lte_200,c_fill,h_120,w_80/if_else,c_fill,h_90,w_100/sample.jpg
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
  {:if=>"w_lte_200", :height=>120, :width=>80, :crop=>"fill"},
  {:if=>"else", :height=>90, :width=>100, :crop=>"fill"}
  ])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
  array("if"=>"w_lte_200", "height"=>120, "width"=>80, "crop"=>"fill"),
  array("if"=>"else", "height"=>90, "width"=>100, "crop"=>"fill")
  )))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
  {'if': "w_lte_200", 'height': 120, 'width': 80, 'crop': "fill"},
  {'if': "else", 'height': 90, 'width': 100, 'crop': "fill"}
  ])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
  {if: "w_lte_200", height: 120, width: 80, crop: "fill"},
  {if: "else", height: 90, width: 100, crop: "fill"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .if("w_lte_200").height(120).width(80).crop("fill").chain()
  .if("else").height(90).width(100).crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
  {if: "w_lte_200", height: 120, width: 80, crop: "fill"},
  {if: "else", height: 90, width: 100, crop: "fill"}
  ]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
  {if: "w_lte_200", height: 120, width: 80, crop: "fill"},
  {if: "else", height: 90, width: 100, crop: "fill"}
  ]})
React:
<Image publicId="sample.jpg" >
  <Transformation if="w_lte_200" height="120" width="80" crop="fill" />
  <Transformation if="else" height="90" width="100" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
  <cld-transformation if="w_lte_200" height="120" width="80" crop="fill" />
  <cld-transformation if="else" height="90" width="100" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
  <cl-transformation if="w_lte_200" height="120" width="80" crop="fill">
  </cl-transformation>
  <cl-transformation if="else" height="90" width="100" crop="fill">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("w_lte_200").Height(120).Width(80).Crop("fill").Chain()
  .If("else").Height(90).Width(100).Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .if("w_lte_200").height(120).width(80).crop("fill").chain()
  .if("else").height(90).width(100).crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("w_lte_200").setHeight(120).setWidth(80).setCrop("fill").chain()
  .setIf("else").setHeight(90).setWidth(100).setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
Else conditions

In cases where the if condition is not in the preceding transformation component, then the if_else parameter also acts as an if_end parameter: all chained transformation components until the one with if_else are only applied if the previous condition holds true. Multiple conditional transformations can also be applied by adding an if_end parameter to the last transformation component in the chain, and to avoid ambiguity, the component with the if_else parameter should not have additional transformation instructions.

For example, if the width is less than or equal to 400 pixels then fill the image to 220x180 and add a red effect, and if the width is greater than 400 pixels then fill the image to 190x300 and add an oil painting effect:

URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NetAndroidiOSAll
URL:
https://res.cloudinary.com/demo/image/upload/if_w_lte_400/c_fill,h_220,w_180/e_red/if_else/c_fill,h_190,w_300/e_oil_paint/if_end/sample.jpg
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
  {:if=>"w_lte_400"},
  {:height=>220, :width=>180, :crop=>"fill"},
  {:effect=>"red"},
  {:if=>"else"},
  {:height=>190, :width=>300, :crop=>"fill"},
  {:effect=>"oil_paint"},
  {:if=>"end"}
  ])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
  array("if"=>"w_lte_400"),
  array("height"=>220, "width"=>180, "crop"=>"fill"),
  array("effect"=>"red"),
  array("if"=>"else"),
  array("height"=>190, "width"=>300, "crop"=>"fill"),
  array("effect"=>"oil_paint"),
  array("if"=>"end")
  )))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
  {'if': "w_lte_400"},
  {'height': 220, 'width': 180, 'crop': "fill"},
  {'effect': "red"},
  {'if': "else"},
  {'height': 190, 'width': 300, 'crop': "fill"},
  {'effect': "oil_paint"},
  {'if': "end"}
  ])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
  {if: "w_lte_400"},
  {height: 220, width: 180, crop: "fill"},
  {effect: "red"},
  {if: "else"},
  {height: 190, width: 300, crop: "fill"},
  {effect: "oil_paint"},
  {if: "end"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .if("w_lte_400").chain()
  .height(220).width(180).crop("fill").chain()
  .effect("red").chain()
  .if("else").chain()
  .height(190).width(300).crop("fill").chain()
  .effect("oil_paint").chain()
  .if("end")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
  {if: "w_lte_400"},
  {height: 220, width: 180, crop: "fill"},
  {effect: "red"},
  {if: "else"},
  {height: 190, width: 300, crop: "fill"},
  {effect: "oil_paint"},
  {if: "end"}
  ]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
  {if: "w_lte_400"},
  {height: 220, width: 180, crop: "fill"},
  {effect: "red"},
  {if: "else"},
  {height: 190, width: 300, crop: "fill"},
  {effect: "oil_paint"},
  {if: "end"}
  ]})
React:
<Image publicId="sample.jpg" >
  <Transformation if="w_lte_400" />
  <Transformation height="220" width="180" crop="fill" />
  <Transformation effect="red" />
  <Transformation if="else" />
  <Transformation height="190" width="300" crop="fill" />
  <Transformation effect="oil_paint" />
  <Transformation if="end" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
  <cld-transformation if="w_lte_400" />
  <cld-transformation height="220" width="180" crop="fill" />
  <cld-transformation effect="red" />
  <cld-transformation if="else" />
  <cld-transformation height="190" width="300" crop="fill" />
  <cld-transformation effect="oil_paint" />
  <cld-transformation if="end" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
  <cl-transformation if="w_lte_400">
  </cl-transformation>
  <cl-transformation height="220" width="180" crop="fill">
  </cl-transformation>
  <cl-transformation effect="red">
  </cl-transformation>
  <cl-transformation if="else">
  </cl-transformation>
  <cl-transformation height="190" width="300" crop="fill">
  </cl-transformation>
  <cl-transformation effect="oil_paint">
  </cl-transformation>
  <cl-transformation if="end">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("w_lte_400").Chain()
  .Height(220).Width(180).Crop("fill").Chain()
  .Effect("red").Chain()
  .If("else").Chain()
  .Height(190).Width(300).Crop("fill").Chain()
  .Effect("oil_paint").Chain()
  .If("end")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .if("w_lte_400").chain()
  .height(220).width(180).crop("fill").chain()
  .effect("red").chain()
  .if("else").chain()
  .height(190).width(300).crop("fill").chain()
  .effect("oil_paint").chain()
  .if("end")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setIf("w_lte_400").chain()
  .setHeight(220).setWidth(180).setCrop("fill").chain()
  .setEffect("red").chain()
  .setIf("else").chain()
  .setHeight(190).setWidth(300).setCrop("fill").chain()
  .setEffect("oil_paint").chain()
  .setIf("end")).generate("sample.jpg")!, cloudinary: cloudinary)
Muiltiple else branch conditions