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:
Configure basic settings:
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:
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:
What happens under the hood:
- The adaptive image component initiates and reads its settings, including the source image path.
- Then it uses Uploadcare Proxy to upload the source image.
- After that, it generates
srcset
for the resulting image and renders theimg
tag into the DOM.
Breakpoints
To create a truly responsive layout, you should specify a list of breakpoints:
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:
Image processing
You can specify transformation settings for the single image or the set of images:
Image transformations operations are separated with /-/
symbols, exactly as specified in the URL API:
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:
To enable intersection observer:
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:
After initiating, if JavaScript is enabled in the browser, that will be transformed into:
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:
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:
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.