> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# Adaptive image component

> The web component for the efficient image representation on any page; generates a set of URLs for the initial image source with the desired parameters.

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.

#### [Adaptive delivery basic example](https://codesandbox.io/s/docs-adaptive-delivery-basic-example-c9hpwq)

View in CodeSandbox

## Quick start

Install the `@uploadcare/file-uploader` package in the same way as in the File Uploader
[installation](/docs/file-uploader/installation/) docs.

Connect the script:

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

Configure basic settings:

```css
uc-img {
  --uc-img-pubkey: '$YOUR_PUBLIC_KEY';
  --uc-img-breakpoints: '200, 500, 800';
}
```

Get `$YOUR_PUBLIC_KEY` from [API keys](https://app.uploadcare.com/projects/-/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](/docs/cdn-operations/#dimensions).

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

```html
<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:

```html
<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](/docs/delivery/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:

```html
<style>
  @import url('./test.css');

  uc-img {
    --uc-img-breakpoints: '400, 800, 1200';
  }
</style>

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

The browser will select the most suitable image size automatically.
Read our article about [responsive images](/docs/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:

```html
<style>
  #target {
    background-size: cover;
  }
</style>
<div id="target">Some text...</div>
<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:

```html
<style>
  .invert {
    --uc-img-cdn-operations: 'invert';
  }
</style>

<uc-img class="invert" src="SOURCE_IMAGE_PATH"></uc-img>
```

[Image transformations](/docs/transformations/image/) operations are separated with `/-/`
symbols, exactly as specified in the [URL API](https://uploadcare.com/docs/api/url/):

```html
<style>
  .invert_grayscale {
    --uc-img-cdn-operations: 'invert/-/grayscale';
  }
  .old_styled {
    --uc-img-cdn-operations: 'saturation/-80/-/contrast/80/-/warmth/50';
  }
</style>
```

## Lazy loading

[Native lazy loading](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe/#attr-loading) is enabled by default
for all image components. You can disable it or use a custom one based on
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).

To disable lazy loading:

```html
<style>
 uc-img {
   --uc-img-lazy: 0;
 }
</style>

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

To enable intersection observer:

```html
<style>
 uc-img {
   --uc-img-intersection: 1;
 }
</style>

<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:

```html
<uc-img src="SOURCE_IMAGE_PATH">
 <noscript>
   <img src="SOURCE_IMAGE_PATH" />
 </noscript>
</uc-img>
```

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

```html
<uc-img src="SOURCE_IMAGE_PATH">
 <img srcset="...GENERATED_SRC_LIST" />
</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:

```html
<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:

```html
<style>
 uc-img {
   --uc-img-is-preview-blur: 0;
 }
</style>

<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.

| CSS context property       | HTML Attribute    | Default value | Type        |
| :------------------------- | :---------------- | :------------ | :---------- |
| --uc-img-dev-mode          | dev-mode          | none          | number flag |
| --uc-img-pubkey            | pubkey            | none          | string      |
| --uc-img-uuid              | uuid              | none          | string      |
| --uc-img-src               | src               | none          | string      |
| --uc-img-lazy              | lazy              | `1`           | number flag |
| --uc-img-intersection      | intersection      | `0`           | number flag |
| --uc-img-breakpoints       | breakpoints       | none          | string      |
| --uc-img-cdn-cname         | cdn-cname         | none          | string      |
| --uc-img-proxy-cname       | proxy-cname       | none          | string      |
| --uc-img-hi-res-support    | hi-res-support    | `1`           | number flag |
| --uc-img-ultra-res-support | ultra-res-support | `0`           | number flag |
| --uc-img-format            | format            | `'webp'`      | string      |
| --uc-img-cdn-operations    | cdn-operations    | none          | string      |
| --uc-img-progressive       | progressive       | none          | number flag |
| --uc-img-quality           | quality           | none          | string      |
| --uc-img-is-background-for | is-background-for | none          | string      |
| --uc-img-is-preview-blur   | is-preview-blur   | `1`           | number flag |