Qwik Image Component

The goal is a component to support performant images on the web and automatic image optimization. That will be built as a pluggable component so devs could connect different image loaders to it (like builder.io or Cloudinary)

Showcase ( network Slow 3G 🤯 )

Installation

npm install qwik-image
or
yarn install qwik-image
or
pnpm install qwik-image

Usage

Global Provider (required)

const imageTransformer$ = $(({ src, width, height }: ImageTransformerProps): string => {
  return `${src}?w=${width}&h=${height}&format=webp`;
});

// Provide your default options
useImageProvider({
  // you can set this property to overwrite default values [640, 960, 1280, 1920, 3840]
  resolutions: [640],
  // you we can define the source from which to load our image
  imageTransformer$,
});

Image component

<Image
  layout="fixed"
  objectFit="cover"
  width="300"
  height="300"
  src={...}
  alt={...}
  placeholder={...}
/>

Picture component (art direction)

Use Picture when you need different image files per viewport (e.g. a full-width desktop banner and a smaller mobile banner from separate CMS fields). It renders a native <picture> element, so the browser downloads only the source whose media query matches — unlike two CSS-hidden <Image> tags, which are both fetched when loading="eager"/fetchpriority="high" are set (hurting LCP).

import { Picture } from 'qwik-image';

export default component$((props) => {
  return (
    <Picture
      layout="fullWidth"
      alt="Banner"
      loading="eager"
      fetchpriority="high"
      src={props.image}                 // fallback / default (desktop)
      sources={[
        { src: props.imageMobile, media: '(max-width: 767px)' },
        { src: props.image,       media: '(min-width: 768px)' },
      ]}
    />
  );
});

The visual difference between breakpoints comes from serving different src files — the desktop and mobile images your CMS already provides. Exactly one of them is downloaded, and loading/fetchpriority (set on the fallback <img>) apply to whichever source the browser selects, so the LCP request is single and correctly prioritized.

Picture accepts every Image prop (layout, objectFit, alt, loading, fetchpriority, class, placeholder, …) and forwards them to the fallback <img>. Each entry in sources is:

field	required	description
src	yes	Image URL for this source (run through your imageTransformer$).
media	yes	Media query, e.g. (min-width: 768px).
type	no	MIME type, e.g. image/webp.
width / height / aspectRatio	no	Per-source overrides for that source's generated srcset, following the same rules as Image (e.g. aspectRatio affects the generated heights only when height is also set). Fall back to the Picture-level values.

loading values:

Here is the loading values and behaviors https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading default: lazy

priority:

Set priority on above-the-fold images (especially the LCP image) so they load eagerly with a high fetch priority. It renders loading="eager" and fetchpriority="high" instead of the default loading="lazy". Use it on at most one or two images per page — never lazy-load the LCP image.

<Image
  layout="constrained"
  width="1200"
  height="600"
  src={...}
  alt={...}
  priority
/>

layout values:

constrained

If the width of the image is larger than the screen, the screen size is taken, otherwise the actual image size is kept

fixed

regardless of the screen width, the width of the image is kept

fullWidth

the width of the image is always equal to the width of the screen

objectFit values:

Here is the objectFit values and behaviors https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit default: cover

placeholder values:

You can define a placeholder to wait for the image to load. default: transparent

background: 'rgba(37,99,235,1)';

background: 'linear-gradient(180deg, rgba(2,0,36,1) 0%, rgba(166,206,247,1) 0%, rgba(37,99,235,1) 83%);';

background: 'url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNUTX59BgAEaQJBWyqr7QAAAABJRU5ErkJggg==")';

background: 'url("/public/placeholder.jpg") no-repeat center / cover';