Repository files navigation

A cross-framework component for responsive, high-performance images using image CDNs

• Just an<img> tag! No extra elements, no runtime JavaScript. Easy to style.No legacy hacks or workarounds.
• Automatically generates correct srcset and sizes attributes for responsiveimages.
• Handles responsive resizing of images, preserving aspect ratio and avoidinglayout shift.
• Uses native lazy loading and async decoding for offscreen images.
• Handles different image layouts: fixed, constrained and full width.
• Uses eager loading and high priority fetching for important images.
• Delivers modern image formats, including WebP and AVIF if supported by thebrowser.
• No build step or server-side rendering required for the images: uses yourexisting image CDN or CMS, with no additional configuration.
• Usesunpic lib to support most image CDNs, includingCloudinary, Imgix, and Shopify.
• Can generate a low-res background image for a blurred placeholder effect, oruse with@unpic/placeholder for moreoptions.

For details of usage, seethe documentation.

While it's easy to use an<img> tag for images, if you want to follow bestpractices and deliver the most performant image to your users then it can take alot of work. Some frontend frameworks will automate this for you, but they oftenrely on slow pre-rendering of images, or on running image optimizers on your ownsite. They also generate complex HTML with wrappers and spacer elements thatmake images hard to style.

Most images on modern websites are hosted on a CDN or CMS that can resize imageson the fly and deliver them at the edge. Despite this, most web frameworks willstill download and resize the image at build time or on your server, rather thanusing the CDN, or just uses a single source image rather than handling multipleresolutions.

This library works with any frontend framework or none, and uses your existingimage CDN or CMS, with no additional configuration.

For more details, seethis post.

This library uses unpic to detect the image CDN, and then uses the CDN's URL APIto resize and format images. It then generates the correctsrcset andsizesattributes for the image. It uses new features built into modern browsers tohandle lazy loading, fetch priority and decoding. It also uses pure CSS tohandle responsive resizing of images, preserving aspect ratio and avoidinglayout shift. Unlike most other image components, it does not use anyclient-side JavaScript by default, and generates just a single<img> tagwithout any wrapper divs or padding elements.

<Imagesrc="https://cdn.shopify.com/static/sample-images/bath_grande_crop_center.jpeg"layout="constrained"width={800}height={600}alt="Shopify"/>

<imgalt="Shopify"loading="lazy"decoding="async"sizes="(min-width: 800px) 800px, 100vw"srcset="    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=1600&amp;height=2133 1600w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=1280&amp;height=1707 1280w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=1080&amp;height=1440 1080w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=960&amp;height=1280   960w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=828&amp;height=1104   828w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=800&amp;height=1067   800w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=750&amp;height=1000   750w,    https://cdn.shopify.com/static/sample-images/bath.jpeg?crop=center&amp;width=640&amp;height=853    640w"src="https://cdn.shopify.com/static/sample-images/bath.jpeg?width=800&amp;height=600&amp;crop=center"style="        object-fit: cover;        max-width: 800px;        max-height: 600px;        aspect-ratio: 1.33333 / 1;        width: 100%;"/>

You can use any image CDN supported byunpic lib,including:

• Adobe Dynamic Media (Scene7)
• Builder.io
• Bunny.net
• Cloudflare
• Contentful
• Cloudinary
• Directus
• Imgix, including Unsplash, DatoCMS, Sanity and Prismic
• Kontent.ai
• Netlify
• Shopify
• Storyblok
• Vercel / Next.js
• WordPress.com and Jetpack Site Accelerator

Published under the MIT licence. ©Matt Kane 2023.