A high-performance, responsive image component for WebC.
Installation and usage
npm install @unpic/webc
@11ty/webc version 0.9.0 or later, because it uses the new
If you are using this with Eleventy, there are a number of ways of defining WebC
components. In the example we’re using
check out the docs
for other options that handle imports automatically. You can then use the
component in your templates:
<unpic-img webc:import="npm:@unpic/webc" src="https://cdn.shopify.com/static/sample-images/bath_grande_crop_center.jpeg" layout="constrained" width="800" height="600" alt="A lovely bath" ></unpic-img>
The component accepts all the props of an
<img> tag, plus the following:
The resizing behaviour of the image.
constrained: (default) the image will be rendered at a maximum of
height, but will scale down automatically if the container is smaller, maintaining the aspect ratio.
fullWidth: the image will be rendered at full width of its container. This is optimized for full-width hero images. You can set
heightto a fixed value, which will mean the image will be rendered at that fixed height and scale horizontally to fill the container.
fixed: the image will be rendered at the exact size specified by
By default, images are loaded lazily. If
priority is set to
true, the image will be loaded eagerly, and will be given high priority by the browser. This is useful for images that are above the fold, particularly large ones such as hero images.
Either an image URL, CSS gradient or CSS colour value. If set to
auto, a low-resolution version of the image will be rendered as a background image, with a blurred placeholder effect. This is still loaded from the remote server, so if you can instead provide an inline base64-encoded version of the image or background colour, you should do that instead. Look at
@unpic/placeholder for a library that can generate these placeholders.
Bear in mind that this is not removed after the image loads, so it will be visible if the image has transparency.
Instead of specifying both
height, you can specify can
By default the CDN is auto-detected from the
src URL. If you want to override this, you can specify a CDN object. See the unpic for supported values.
By default the image breakpoints used in the
srcset are generated based on the layout and image size. You can override this by specifying an array of breakpoints. The breakpoints are specified as an array of numbers, representing the width of the image in pixels.
Any prop supported by
<img> tags can be passed in, except
srcset which is generated from
src. The following props are set automatically, but can be overridden if you need to: