Last updated: Apr-19-2023
If you want to automate only the width of the image without taking the device's DPR into account, then it is preferable to use the frontend frameworks solution.
Cloudinary's cloudinary-core library includes a method that automatically builds the dynamic image URLs and works as follows:
- A Cloudinary dynamic transformation URL is automatically built on the fly to deliver an image that is scaled to the exact available width and resolution.
- If the browser window is consequently enlarged then new higher resolution images are automatically delivered, while using breakpoint steps (every 100px by default) to prevent loading too many images.
- If the browser window is scaled down, browser-side scaling is used instead of delivering a new image.
This feature allows you to upload one high resolution image to Cloudinary, and have it automatically adapt to the resolution and size appropriate to each user's device or browser on the fly.
w_autowith the actual values on the client side based on the screen properties and viewport width. In contrast, the Client-Hints based solution allows you to simplify your code and perform the dynamic decisions on the server side (CDN level) based on Client-Hints, but only for supported browsers.
Automating responsiveness with the cloudinary-core JS library
See how the layout and images (including the text overlays) dynamically respond to the width of the browser when this responsive solution is used. Follow the steps below to implement the responsive solution with the cloudinary-core JS library.
- The text overlays change based on the DPR of the device and the width of the delivered image (
w_autoare replaced with the actual values on the client side based on the screen properties and viewport width.
- When the browser width is wide, the first images delivered are smaller in dimensions. As you make the browser narrower, the individual columns get more space on the next breakpoint, so larger images are requested to fill the larger available space.
- The change in overlay width indicates that a new image was requested and displayed.
- When increasing the width of the page, as the largest version with the best resolution was already requested and delivered, that version is used and scaled down on the client side, so the overlays don't change back.
Include the Cloudinary cloudinary-core library in your HTML pages:
cloudinary-core-shrinkwrap.jslibrary is a shrinkwrapped version of the
cloudinary-corelibrary (it is not dependent on
- Instead of installing the files, the latest version of the
cloudinary-corefiles can also be directly referenced from
https://unpkg.com/cloudinary-core@latest/cloudinary-core-shrinkwrap.js. For production use, we recommend that you use a specific version, and not the latest, to protect yourself from any breaking changes.
Step 2: set the img tag parameters
For each image to display responsively:
- Set the
data-srcattribute of the
imgtag to the URL of an image that was uploaded to Cloudinary. There is no need to set the
srcattribute of the
imgtag as it is updated dynamically. However, you can optionally set the src attribute to a placeholder image that is displayed until the image is loaded.
- Set the
c_limit,w_auto/dpr_autoin URLs). This allows the SDK to dynamically generate an image URL scaled to the correct width value, based on the DPR of the device and the detected width actually available for the image in the containing element.
- Add the
cld-responsiveclass to the image tag. This is the default class name, but you can use custom class names and programmatically make HTML elements become responsive.
Step 3: call the Cloudinary responsive method
Add a call to Cloudinary's
responsive method looks for all images in the page that have the "cld-responsive" class name, detects the available width for the image on the page, and then updates the HTML image tags accordingly. The image is also updated whenever the viewport size or screen resolution changes.
Responsive images using the cloudinary-core JS library interactive demo
Try this responsive demo to see how the browser loads different sized images based on the viewport width.
See notes on this demo.
View the demo code in GitHub.
Overriding default values
By default, the responsive method uses a breakpoint steps value of 100 pixels, and always uses the breakpoints to determine the width. These values can be overridden by using the
config method to pass new values for the
responsive_use_breakpoints parameters as follows:
breakpoints: A function or set of values to be used when resizing the browser window and a larger image needs to be delivered. For example:
a function to set the breakpoints steps to every 50 pixels:
an array of values:
responsive_use_breakpoints: A string value determining when to use the breakpoint steps:
- true - (default) always use breakpoints for width.
- resize - use the exact width of the containing element on initial render, then proceed with breakpoints.
- false - always use the containing element's width.
Both of the above parameters need to be passed with the
config method. For example, calling to Cloudinary's
The responsive design can be implemented with the Cloudinary SDK's helper methods (e.g.
cl_image_tag in Ruby on Rails). Setting the
crop parameter to
limit and the
dpr parameters to
auto creates an HTML image tag with a blank
src attribute while the
data-src attribute points to a dynamic image transformation URL. When you load Cloudinary's
cloudinary-core library and call the
responsive_placeholder parameter, or set it to an inline blank image by setting the parameter to
For example, creating an HTML image tag for the "smiling_man.jpg" image with the width automatically determined on the fly as needed, and using a blank image placeholder:
The code above generates the following HTML image tag: