How to load responsive images with lr-img

Efficient image handling is crucial for maintaining fast and responsive websites. One key aspect of this is image optimization, which ensures images load quickly without compromising quality.

Uploadcare’s lr-img block is a web component for images designed to optimize image performance, provide a seamless user experience, and improve overall website metrics. This article will guide you through using the lr-img component on any webpage.

What is Uploadcare lr-img?

The lr-img block is an adaptive image component designed to help serve images that can adapt to different screen sizes and serve optimized images. By using lr-img in your websites you can automatically generate adaptive images for different devices, enhancing performance whether images are stored on Uploadcare or not.

Configure the lr-img component for usage.

To use the lr-img component, head to your Uploadcare Project Dashboard -> API keys and copy the Public API key. In the head tag of your page, add the block script to import the lr-img component:

<script src="" type="module"></script>

Next, create a style element to configure the component:

lr-img {
  --lr-img-pubkey: 'YOUR_PUBLIC_KEY';

lr-img img {
  width: 100%;
  height: auto;

Replace YOUR_PUBLIC_KEY with your Public key from your Uploadcare project.

If your images are not uploaded to Uploadcare, you can use Uploadcare proxy to automatically source for the images for Uploadcare to use.

To do this, head to your Uploadcare project → Settings, click on the Delivery tab and add a domain to the list of Allowed domains for Proxy.

Uploadcare Proxy settingsUploadcare Proxy settings

For this tutorial, you’ll source an image from

In your webpage you can now use the image component with images from allowed domain like this:

<lr-img src=""></lr-img>

If your files are already uploaded to Uploadcare, you can use the image component with your images, using the UUID of your images:

<lr-img uuid="d79bfc01-e76f-4b60-b1b2-409fe5b73735"></lr-img>

Key features of Uploadcare lr-img

Responsive image delivery

The component generates a srcset with desired breakpoints, delivering the right image size based on the user’s device and screen resolution. This responsive approach improves load times and ensures high-quality images for all users.

Add this following code to set breakpoints for the image:

lr-img {
  --lr-img-pubkey: 'YOUR_PUBLIC_KEY';
  --lr-img-breakpoints: '600, 900, 1200';

lr-img img {
  width: 100%;
  height: auto;
Responsive image delivery on desktopResponsive image delivery on desktop

Notice the size of the image the browser renders on screens larger than 1200px.

In smaller devices, around 600px, the browser renders a smaller image with a lower file size but still of high quality.

Responsive image delivery on mobileResponsive image delivery on mobile

Automatic image optimization

The lr-img component automatically optimizes images, ensuring they are resized and compressed effectively. This seamless process requires no manual intervention, providing consistent optimization across all images. Based on the screen breakpoint, the component determines which image format is best and optimized and renders it on the browser.

In the previous example above notice how the WEBP image formats is served in large screens and AVIF image format is served in smaller screens.

This ensures that images are well optimized for device it is being displayed on.

Lazy loading

Lazy loading is enabled by default, deferring the loading of images until they are needed. This technique reduces initial page load time and conserves bandwidth, leading to a faster and more efficient browsing experience.

Image transformation operations

When using the lr-img component, you can apply image transformation operations from Uploadcare. To do this, use the --lr-img-cdn-operations property in the config:

lr-img {
  --lr-img-pubkey: 'YOUR_PUBLIC_KEY';
  --lr-img-breakpoints: '600, 900, 1200';
  --lr-img-cdn-operations: '-/crop/800x600/1325,1000/';

The transformation applied above crops the image to show only a specific section of the image.

Image transformation operationsImage transformation operations

To learn more about transformations that you can apply to your images visit the documentation on image transformation.

Adaptive background images

The component allows for the creation of adaptive background images using the is-background-for attribute. This feature ensures that background images are optimized and responsive, improving the visual appeal and performance of your site.

To use the lr-img for background images, create a div with an id and provide it as a value for the is-background-for property for the component:

<div id="bg-image">Text with Background Image</div>

To style the div, add the following CSS to the page:

#bg-image {
  background-size: cover;
  height: 500px;
  color: #fff;
  font-size: 50px;
  background-position: center;

This should provide you with a div and background image that looks like this:

Adaptive background imageAdaptive background image

Benefits of using Uploadcare lr-img

Using the lr-img component for displaying images over the standard img provides you with a wide range of benefits for optimizing image performance and enhancing the user experience on your website. Here are some key advantages:

Improved website performance

Optimized images are loaded faster, reducing overall website load time. This enhances user experience, reduces bounce rates.

Enhanced user experience

Fast-loading images contribute to a smoother and more enjoyable user experience. When images are loaded quickly, visitors are more likely to stay and engage with content, leading to higher conversion rates and user satisfaction.

Reduced bandwidth usage

By optimizing images, Uploadcare lr-img component reduces the amount of data transferred. This results in significant bandwidth savings, especially for websites with high traffic or numerous images.


Uploadcare lr-img is a useful tool for optimizing image performance on your website. With features like optimization, responsive image delivery, lazy loading, and adaptive background images, lr-img enhances your site’s performance and user experience.

For more information about image optimization and advanced image transformation features, visit the Uploadcare Documentation.

Build file handling in minutesStart for free

Ready to get started?

Join developers who use Uploadcare to build file handling quickly and reliably.

Sign up for free