What are named transformations and how to use them

A transformation is essentially one or more instructions that tell Cloudinary how to change the properties of a media asset. Cloudinary transformations are displayed as abbreviated parameters directly in the URL that accesses the media.

What are named transformations?

Named transformations allow you to take one or more transformations, and group them under a unique custom name.

Once a named transformation has been defined, calling that named transformation would apply all of the transformations in that set without the need to specifically list out each one.

For example, if we take the image below with this URL:

https://res.cloudinary.com/demo/image/upload/docs/billiards.jpg

We could apply the following transformations:

• Change the width of the image to be 300px and the height 200px using `h_200,w_300`
• Scale the image to fit the requested dimensions using `c_scale`
• Improve the quality of the image using the improve effect: `e_improve`
• Apply a quality optimization to the image to retain the quality while still decreasing its size using `q_auto:good`

Applying all of these transformations would make the URL as follows:

https://res.cloudinary.com/demo/image/upload/c_scale,e_improve,h_200,q_auto:good,w_300/docs/billiards.jpg

We could use a named transformation to group all of the above transformations under one name. In this case, we created a named transformation called `improved`. You can include a named transformation in the URL with the syntax t_<name of transformation>. t_improved in the case of our example below.  By calling just that one named transformation, all of the transformations we previously defined in that set would be applied. Now the URL looks as follows:

https://res.cloudinary.com/demo/image/upload/t_improved/docs/billiards.jpg

You can find a comprehensive guide to named transformation in our documentation

What are named transformations good for?

Named transformations are great if you have a set of transformations that you are using regularly, or a complex transformation used often. Defining a named transformation for that set of transformations would allow us to easily apply the entire set without repeating it every time.

Another reason for using named transformation might be if you want to disguise a specific set of transformations from being publicly known. Creating a named transformation for that transformation set would display only the named transformation on the resource URL rather than the entire set of transformation parameters.

How to define named transformations

Named transformations can be defined through our Management Console or Admin API.

Why can't I use `q_auto` or `f_auto` in a named transformation?

When using the f_auto parameter, the actual format to be fetched is determined on the CDN level. Therefore the f_auto component must remain visible to the CDN and cannot be used within a named transformation. 

In addition, the q_auto component cannot be used within a named transformation as well. This is because the mode of the q_auto parameter to be used is dependent on the browser receiving the resource. Note that using the  q_auto:[Mode] component can be used in a named transformation since the resolution of that is not dependent on the browser.

You can read more about f_auto and q_auto being used in named transformations here