Adaptive image component

Uploadcare provides a web component for efficient image representation on any page. Simply replace <img> tags with <uc-img>, and it will generate a srcset with adapted images. It works regardless of whether images are stored on Uploadcare or not.

Use the adaptive image to automatically:

• Optimize image size even without uploading to Uploadcare.
• Generate srcset with desired breakpoints.
• Create adaptive background images.

Quick start

Install the @uploadcare/file-uploader package in the same way as in the File Uploader installation docs.

Connect the script:

1
<script src="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-img.min.js" type="module"></script>

Configure basic settings:

1
   uc-img {
2
     --uc-img-pubkey: '$YOUR_PUBLIC_KEY';
3
     --uc-img-breakpoints: '200, 500, 800';
4
}

Get $YOUR_PUBLIC_KEY from API keys. A public key is necessary if your images aren’t yet uploaded to the Uploadcare.

If you need to work with src, then you also need to add a domain in the project settings.

Note: The maximum breakpoint value is 1500 because, at double pixel density, this conducts to 3000px images, which is the maximum resolution for image processing. Learn more about image size limit.

Then use <uc-img> tag for the images in your HTML templates:

1
<uc-img src="SOURCE_IMAGE_PATH"></uc-img>

If your files are already uploaded to Uploadcare, you don’t need to add a public key and should use the files’ UUIDs instead of the source image path:

1
<uc-img uuid="UUID"></uc-img>

What happens under the hood:

1. The adaptive image component initiates and reads its settings, including the source image path.
2. Then it uses Uploadcare Proxy to upload the source image.
3. After that, it generates srcset for the resulting image and renders the img tag into the DOM.

Breakpoints

To create a truly responsive layout, you should specify a list of breakpoints:

1
<style>
2
  @import url('./test.css');
3
4
  uc-img {
5
    --uc-img-breakpoints: '400, 800, 1200';
6
  }
7
</style>
8
9
<uc-img src="SOURCE_IMAGE_PATH"></uc-img>

The browser will select the most suitable image size automatically. Read our article about responsive images to learn more about it.

Background mode

To make it work for the element’s background, add the is-background-for attribute with the desired element’s CSS selector in its value:

1
<style>
2
  #target {
3
    background-size: cover;
4
  }
5
</style>
6
<div id="target">Some text...</div>
7
<uc-img is-background-for="#target" src="SOURCE_IMAGE_PATH"></uc-img>

Image processing

You can specify transformation settings for the single image or the set of images:

1
<style>
2
  .invert {
3
    --uc-img-cdn-operations: 'invert';
4
  }
5
</style>
6
7
<uc-img class="invert" src="SOURCE_IMAGE_PATH"></uc-img>

Image transformations operations are separated with /-/ symbols, exactly as specified in the URL API:

1
<style>
2
  .invert_grayscale {
3
    --uc-img-cdn-operations: 'invert/-/grayscale';
4
  }
5
  .old_styled {
6
    --uc-img-cdn-operations: 'saturation/-80/-/contrast/80/-/warmth/50';
7
  }
8
</style>

Lazy loading

Native lazy loading is enabled by default for all image components. You can disable it or use a custom one based on IntersectionObserver.

To disable lazy loading:

1
<style>
2
 uc-img {
3
   --uc-img-lazy: 0;
4
 }
5
</style>
6
7
<uc-img src="SOURCE_IMAGE_PATH"></uc-img>

To enable intersection observer:

1
<style>
2
 uc-img {
3
   --uc-img-intersection: 1;
4
 }
5
</style>
6
7
<uc-img src="SOURCE_IMAGE_PATH"></uc-img>

Layout shift

To avoid layout shifts during loading, setting the initial size of the images is recommended.

Fallback

For SEO or NOSCRIPT purposes, use <noscript> sections in your integrations with the original image path:

1
<uc-img src="SOURCE_IMAGE_PATH">
2
 <noscript>
3
   <img src="SOURCE_IMAGE_PATH" />
4
 </noscript>
5
</uc-img>

After initiating, if JavaScript is enabled in the browser, that will be transformed into:

1
<uc-img src="SOURCE_IMAGE_PATH">
2
 <img srcset="...GENERATED_SRC_LIST" />
3
</uc-img>

Development mode (relative image path)

When you develop an application, use a local development server and relative paths in your project structure for the images:

1
<uc-img src="../LOCAL_IMAGE_PATH"></uc-img>

In that case, Uploadcare Proxy would be disabled for your development environment, and you will see original local images in your application until you deploy it.

Preview blur

Using the is-preview-blur attribute, you can quickly get your image blurred to show to the user while the main image is loading.

It is ON by default. To disable blur preview:

1
<style>
2
 uc-img {
3
   --uc-img-is-preview-blur: 0;
4
 }
5
</style>
6
7
<uc-img src="SOURCE_IMAGE_PATH"></uc-img>

Note: If the is-background-for attribute is applied, then the is-preview-blur attribute will not work.

Settings

CSS context properties are available for any container’s nested element, just like any other CSS property. HTML attribute settings have more priority and can redefine other settings.